About the website

This website is created with a Haskell program which compiles pages from Markdown to HTML using the Hakyll static website generator and the Pandoc document converter. The program, presented below in literate form, assembles a navigation menu from YAML metadata headers, resolves relative references, typesets mathematical equations using server-side MathJax, and optionally includes a bibliography and table of contents.

The source of the website is published at https://git.colberg.org/peter/peter.colberg.org.

1 Prerequisites

On Debian 10 “Buster”, the following packages are required:

apt install libghc-hakyll-dev libghc-io-streams-dev npm

As non-root user, the required JavaScript modules are installed within the working tree:

npm ci

The Makefile compiles the site program and deploys the website to a separate git branch.

2 Math rendering

The program begins by spawning MathJax in a background Node.js process.

Rather than rendering each page separately using Hakyll’s unixFilter and incurring the overhead of loading MathJax repeatedly, the program communicates with this background process via standard input and output streams to render all mathematical equations. A Pandoc filter submits each equation in TeX format to the MathJax process as a JSON-encoded request and receives the typeset HTML (see MathJax.hs and MathJax.js).

3 Pandoc compiler

A custom Pandoc compiler converts pages from Markdown to HTML.

The Markdown is parsed into a Pandoc AST, which is processed with a chain of Pandoc filters. A bibliography is created with pandoc-citeproc from references given in a separate YAML metadata block that is parsed by Pandoc (see, e.g., nano-dimer/README.md). The AST is rendered as HTML, optionally prepending a table of contents.

4 Hakyll rules

Hakyll is invoked with a set of routes and compilation rules for the site’s resources, where a route is the path of a resource in the output directory. Hakyll tracks dependencies between resources and recompiles pages when the underlying sources are updated, which is particularly useful when previewing drafts with the built-in webserver.

The style sheet is created by concatenating and minimizing all CSS source files.

After Pandoc compilation, the page template adds the title, navigation menu and footer.

Projects have their own home page and navigation menu.

5 Clean routes

For user-friendly URLs, each page is stored in a separate directory with the filename index.html.

All-uppercase path elements are transformed to lowercase, e.g., NEWS.md becomes news/index.html.

The filename index.html is stripped when referencing pages within the website.

7 Relative references

Images and links to internal resources are given as relative references. A Pandoc filter transforms the relative references to the corresponding routes, preserving the fragment identifier that links to a section of a page.

8 Table of contents

If the metadata contains a toc field, a table of contents is generated from headings down to the given depth.