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:

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:

Special Makefile targets

There are three special Makefile targets that you use to operate this 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?

These writings represent my opinions and are not related to my employers.
Licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.