README (5438B)
1 # miniblog 2 3 miniblog is a minimal, configurable static blog system written entirely in Common Lisp and intended primarily for standalone use as a command-line tool. It allows simple creation and management of posts written in Markdown, created and edited through your favorite text editor. By default it uses sqlite3 as a persistence backend and pushes all generated content into date-structured directories as a normal HTML. 4 5 ## Installation/Building 6 7 Clone into ~/common-lisp/miniblog/ (or wherever ASDF and Quicklisp are set up to find your local systems): 8 9 $ cd ~/common-lisp/ 10 $ git clone https://tilde.town/~decaydjk/miniblog.git 11 12 From the REPL of your favorite CL implementation: 13 14 (ql:quickload 'miniblog) 15 16 This will download the required dependencies and compile miniblog for you. If you would like to make a binary that can be executed directly from the command-line: 17 18 (asdf:make 'miniblog/executable) 19 20 This will make an executable named "miniblog" in the system directory. 21 22 Alternatively (especially since CL binaries tend to be a bit massive), you may just want to use a launcher script. Create the following file wherever you would like (I have it as ~/miniblog.lisp). Be sure to fix the shebang line for your chosen CL; you may also have to fix the location of setup.lisp if your quicklisp is not in the usual location. 23 24 #!/usr/bin/sbcl --script 25 26 (require 'asdf) 27 (setf *load-verbose* nil) 28 (setf *load-print* nil) 29 (setf *compile-verbose* nil) 30 (setf *compile-print* nil) 31 (let ((*error-output* (make-broadcast-stream))) 32 (load "~/quicklisp/setup.lisp") 33 (asdf:load-system 'miniblog)) 34 (miniblog:entry-point) 35 36 This will work just like the binary although it takes a moment to start. 37 38 ## Usage 39 40 $ ~/miniblog.lisp -h 41 --add -a boolean Add new post 42 --edit -e integer Edit a post by ID 43 --get -g integer Get a post by ID 44 --delete -d integer Delete a post by ID 45 --list -l boolean List posts 46 --start -s integer When listing posts, first post to list (default 0) 47 -n integer When listing posts, max number of posts to list (default all) 48 --page -p boolean This parameter specifies operations to be done on pages, rather than posts. EG saying -a -p means you intend to add a new page rather than a new post. Page IDs are in a separate namespace from post IDs. 49 --move -m integer Move a page from its current path to a new one. 50 --uri -u string When adding a new page, this specifies the path to the new page in relative URI format. For instance, "-a -p -u foo/bar" would specify that the new page should be created with the name bar as a child of page foo. This is only valid if root page foo actually exists. This isalso used in conjunction with -m to specify the target path for the page being moved, with the same restriction. A leading / will be ignored so "-u /foo/bar/baz" and "-u foo/bar/baz" mean the same thing. 51 --children-to-root -c boolean When deleting a page, normally child pages of the page being deleted will be moved to the parent page of the deleted page. If -c is specified, the pages will instead be moved to the root. 52 --regen-all -r boolean When adding or editing, regenerate all pages instead of just those miniblog thinks have changed. Can also be invoked standalone to regenerate the HTML directly. 53 54 By default, add and edit will use whatever editor you have specified in EDITOR, otherwise will fall back to vi. Posts (and pages) are written in a convenient format: 55 56 [Title] 57 58 [Content in Markdown] 59 60 and will be published immediately. 61 62 ## Configuration 63 64 Configuration is simple, executable Common Lisp in the file ~/.miniblogrc. A sample minimal configuration file: 65 66 (in-package :miniblog) 67 68 (setf *blog-timezone* (local-time:find-timezone-by-location-name "US/Pacific")) 69 (setf *blog-title* "Decay's Miniblog") 70 71 This will set the timezone of your posts to Pacific and your blog title to "Decay's Miniblog". There are other configurable globals (please see src/miniblog.lisp for the complete list) and since .miniblogrc is (load)ed it can contain any arbitrary executable Lisp code. 72 73 ## RSS Support 74 75 Miniblog now has basic RSS 2.0 support! At minimum you will need to configure *BLOG-TITLE*, *BLOG-DESCRIPTION* and *BLOG-LINK* as described in src/miniblog.lisp to provide the basic RSS channel elements. 76 77 ## Contributing 78 79 Email your pull requests to decaydjk@tilde.town over local mail, or decay@todayiwilllaunchmyinfantsonintoorbit.com over standard email! If you have requests or suggestions, hit me up as well and let's talk about it! 80 81 ## Bugs/Issues 82 83 Right now the automatic regeneration is pretty simpleminded. It should work correctly on adds or deletes but in case you run into a tricky edge case you can always request a full regeneration. Also, the rss.xml will not currently be removed if it's present but has been deconfigured, it will just no longer be updated which may not be what you want. 84 85 Some improvements that would be nice: 86 87 * Creating individual files per post so they can be linked independently. 88 * Appropriate meta tags to make the mobile display nicer 89 * Clearer ways of adding a user template 90 * Probably a lot of other stuff! 91 92 ## License 93 94 GNU GPL 3.0 or later (https://choosealicense.com/licenses/gpl-3.0/)