miniblog

Miniblog: A command-line static blog system in Common Lisp
Log | Files | Refs | README | LICENSE

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/)