What Is SSGSS?

This system is too simple for a complex site, but is good enough for mine. I'm intending to add support for a partially automated blog, but the manual effort now is low enough that I don't particularly care.


Due to the way the SSGSS system works, different Markdown engines can be swapped in for generation, with different pros and cons. These are a few I have at least tried:

The requirements for a Markdown processor to work with SSGSS are as follows:

  1. Takes Markdown on standard input.
  2. Produces HTML on standard output.
  3. Does not escape HTML code or attempt to add <html><body> tags etc.


Pages are preprocessed by GNU M4, which provides various highly useful utilities. For example, when writing Markdown, I may want to make links that point to other pages on the site, with the .md extension so I can move between the Markdown source files by using the gf binding in Vim. However, on the actual website, the links must point to the generated html files. To solve this, I can use the following M4 macro:
m4_define(`SSGPAGE', `m4_patsubst($1, .md, .html)')
This allows me to link to the Markdown file in the source, but have the link redirect to the html file after it is processed:



I could theoretically make it more useful by automatically inserting the Markdown link syntax, but that is so simple that I decided I preferred just replacing the extension.

The Pipeline

This is an oversimplified view of the SSGSS pipeline:

markdown < page.md | m4 -P > page.html

There are additional headers and M4 macro files loaded, but the key point is that the Markdown engine is called before M4. This means that M4 macros cannot insert Markdown, since once the text reaches M4, Markdown conversion has already occurred. This is primarily done so M4 doesn't get confused by Markdown code blocks, which are delimited by back-tics (`).