A Minimalist Static Site Generator

Aug 25, 2020

So far I have been using Hugo with a customized version of the Hermit theme to generate this site. This worked well and looked nice. However, Hugo is a relatively complex framework that keeps evolving (occasionally breaking stuff on updates) and the theme consists of a lot of files with styles, templates and scripts that I needed to maintain by myself since I customized them (in a not so clean way). Overall it felt like overkill for my purposes and being on vacation, I hacked together my own minimalist site generator that suits my needs.

As the basis I use a Makefile that copies static files and calls a Rust script on each changed Markdown file to transform it into HTML. The Makefile gives me incremental builds out of the box, only the index page and the RSS feed need to be regenerated before publishing new pages. The Markdown files consist of (1) a header with meta data, deserialized with Serde, and (2) the actual Markdown, transformed to HTML with pulldown-cmark. The header declares an Askama template which is filled with the Markdown content and optionally further data from the header, e.g., page title, creation date, meta description, script and style paths. Predefined keywords enable features such as math typesetting with MathJax and syntax highlighting with highlight.js.

After saving a Markdown file, the VSCode extension Run on Save executes make to generate HTML from the changed file. In the background Browsersync is watching the output directory and automatically refreshes the browser on changes. So writing and editing is the same as before, but now I have full control of the generation process, don't need to read any manuals, and can get by with a bare minimum of CSS and JavaScript.

Updated on Mar 19, 2021.