squeeze

A static site generator that can put the toothpaste back in the tube.
git clone https://git.mulligrubs.me/squeeze
Log | Files | Refs | README | LICENSE

README (3658B)


      1 # Squeeze
      2 
      3 A static site generator that can put the toothpaste back in the tube.
      4 
      5 ## What is this?
      6 
      7 A few months ago I lost the source files I used to generate my static website.
      8 Fortunately there was no irreparable data loss because I still had the
      9 generated site up on my server. The problem was now I needed to write a script
     10 that would extract all the articles into source files again, and then I'd have
     11 to reconfigure the site generator. Then I went, "Oh. This is a Prolog
     12 problem." (But then I love Prolog so every problem is a Prolog problem. I
     13 don't care. Fight me.) A Prolog program is basically a set of rules and the
     14 logic that's guided by those rules can be run in either direction. I figured
     15 if I could write a Prolog program that described my HTML template then I could
     16 use the same code both to un-generate and re-generate the website.
     17 
     18 So the skinny is I wound up writing my own static website generator in Prolog.
     19 Well, the main components are in Prolog. I also wrote a shell script to make
     20 use of a bunch of common \*nix utilities (find, sed, grep, etc.) and to pipe
     21 output to some third-party programs where I needed them (Markdown and
     22 SmartyPants). Weirdest bit was that I just couldn't find anything decent to
     23 generate RSS feeds. I considered dropping the RSS all together, but I've spent
     24 enough time haranguing people for not supporting interoperable standards that
     25 I didn't want to be a hypocrite. I wound up writing my own RSS generator too,
     26 also in Prolog.
     27 
     28 It's pretty closely tailored to my specific needs, but it works, and IMHO it
     29 works better than my old site generator which injected a bunch of nonsense
     30 into my HTML. To make this work for your site, all you need to do is set some
     31 config values in `site.pl` and define your template in `html.pl`.
     32 
     33 ## Dependencies
     34 
     35 * A POSIX shell. Used to run the script that automates everything else.
     36 * A Prolog interpreter. Tested with [SWI-Prolog](https://www.swi-prolog.org/)
     37   and [GNU Prolog](http://www.ohloh.net/p/gprolog), but the syntax aims to be
     38   vanilla ISO Prolog and should work with any implementation.
     39 * [Markdown](https://daringfireball.net/projects/markdown/). Used to convert
     40   Markdown to HTML.
     41 * [SmartyPants](https://daringfireball.net/projects/smartypants/). Used to
     42   smarten the punctuation in the HTML output.
     43 
     44 ## Assumptions
     45 
     46 Your website folder is expected to contain four things:
     47 
     48 * a `source` folder containing the website's source files;
     49 * an `output` folder containing the website's static output;
     50 * a `site.pl` file containing site-specific definitions;
     51 * an `html.pl` file containing your site template.
     52 
     53 One or the other of the `source` and `output` folders must be populated, but
     54 not necessarily both. In the case of saving a website for which you've lost
     55 the source code, you'd populate `output`, ungenerate the site, then commit the
     56 contents of `source` to version control.
     57 
     58 An example `site.pl` and `html.pl` are included in the `example` folder of
     59 this repo.
     60 
     61 ## Use
     62 
     63 Generate a static website from Markdown sources:
     64 
     65 	./squeeze.sh /home/user/website
     66 
     67 Generate source files from a static website:
     68 
     69 	./unsqueeze.sh /home/user/website
     70 
     71 ## Notes
     72 
     73 The Markdown converter is called from inside Prolog, so the path to your
     74 Markdown (and any arguments) is specified in `site.pl`. This allows you to
     75 have different Markdown converters or arguments on a per-site basis.
     76 
     77 Because ISO Prolog doesn't support making calls to external programs, I've
     78 implemented a compatibility layer that allows you to define the
     79 `markdown_to_html` predicate for whatever dialect of Prolog you happen to use.
     80 Included are compatibility predicates for SWI-Prolog and GNU Prolog.