Pandoc as a site generator

For the longest time, I’ve been a fan of Jekyll static site generator. Recently I found myself wanting to publish some brand new web work and reached to reinstall it, as I’d last used the version from ~2013. The installation was easy, but I realized that Jekyll tries to install more Ruby gems at runtime, and has, in general, caught a case of the bloats.

As it’s easier to create the wrong solution than to understand the correct one, I figured I could create my solution based on the technology I know and use regularly: GNU Make and Pandoc.

Pandoc is the universal document converter: it can convert textual documents between all kinds of markup formats. Most of my experience with it was using it to generate all manner of e-books from a single set of source files.

Prerequisites

To use this generator, you will need to have Pandoc and GNU Make installed on your system. After installing the prerequisites, fork the project from Pandoc-SSG Github. A single Makefile is all there is to this tool, and no other installation is required.

Your website will need a theme. The GitHub repo provides a trivial theme, which you can build upon.

Structure of your project

There are two special directories included in the default distribution:

• _pandoc holds the template and configuration files used by Pandoc to drive the generation of your website (it’s what Pandoc refers to as your user data directory)
• _output is where all the generated files live

All of the other content lives in and is generated based off of the top directory of the project - the one that contains the Makefile.

Input format

This generator assumes that all of your posts are stored as Markdown files with the .md file extension.

I will be using Pandoc’s ability to provide YAML metadata at the start of a file, by enclosing it in dashes:

---
title: Some title
---

12345678901234567890123456789012345678901234567890123456789012345678901234567890

Actual text of your post...

This form of providing inline metadata is also present in other static website generator projects. Both Hugo and Jekyll call it “front matter.”

Pandoc variables title and abstract are used by this system to create the blurb files for individual articles. The variable template is used by Pandoc to pick the template from the options in _pandoc/templates/.

You can also define and other variable, and use its value inside your templates.

Functionality

This generator will do the following:

• It will start from the current directory and inspect files and directories recursively (those whose name matches the shell pattern [a-zA-Z0-9]*)
• For any file that is not a Markdown file (doesn’t have a .md file extension), it will simply copy the file into the same location in the _output directory
• For any Markdown file it will invoke Pandoc to convert it to a standalone HTML file based on the default.html5 Pandoc template in _pandoc/templates/default.html5.
  • It will also generate a blurb file based on the blurb.html5 template that includes a link to the document, its title and the document abstract from the metadata. If the document has no abstract, no blurb will be generated.
  • Aditionally, if the filename is index.md, it will append all of the blurbs of articles in all of the subdirectories below the current working directory to the end of the index.md template. This is how you can generate article indices / index pages. The blurbs will be lexicographially sorted based on the full file path.

Special Makefile targets

There are three special Makefile targets that you use to operate this project:

• _build is the target that will perform the generation of the site, and is the default action to take if no other action is specified
• _serve uses Python3’s http.server module to serve the files from _output on all local interfaces on port 8000 so you can view your site locally
• _clean will delete all of the files in the _output directory, forcing a full regeneration of the project

Automating the edit-rebuild cycle

While you can edit the files and manually trigger the building of the website, you can also use an external tool to detect changes and call Make.

I usually use this generator in a combination with fswatch to monitor for changes:

$ make _clean _build
$ while [ true ]; do fswatch -1 .; make; done

This will purge your local build directory, rebuild your site, and then go into an infinite loop that will wait for file changes and rebuild when they occur.

In closing…

While I acknowledge that this generator is very minimal, you may find that it does all that you need for a simple personal site. It’s performant enough for this usage, but it’ll likely be slow with a huge number of files, at least on initial builds.

Certainly not as powerful as other generators, I think this one is interesting in its simplicity above everything else.

Maybe it will be useful to you too?