Miller Hall

November 13, 2021

Build a website with pandoc and GitHub pages

GitHub pages is an awesome tool for building a website. If you don’t set up any themes or configure jekyll to transform markdown, you can still have a pretty easy setup and automation. I’ve set up this website using Amazon Route53, GitHub pages, and pandoc with GitHub actions.

Pages hosts the site at https://arlindohall.github.io, but I wanted to use a custom domain, so I used GitHub pages’ built-in support for custom domains.

When I first set up the website, I built the HTML by hand, but I quickly realized that I was re-using huge chunks of HTML for each page. At that point I tried to use CommonMark JS to compile the markdown pages into HTML, which gave me anchor links and other cool features, but I didn’t like the build process, so I kept looking.

I’ve used pandoc in the past to build PDF documents and slides, so I gave it a try and found that by using a template I could get almost all of the functionality I wanted. On top of that, by using a few plugins and a tiny bit of javascript, I was able to get a fully static, performant, and accessible website using the following steps.

Pandoc actions

The script compile.sh reads the files in _posts and _root, (which get ignored by pages) and compiles them with pandoc into HTML, with the output directories of posts and / respectively.

The script gets run by GitHub actions after installing pandoc (you have to run apt as root to install in actions). Then I use GitHub actions’ push functionality to commit the changes back to the repo. This way I only have to write markdown and then the HTML gets auto-generated by actions.

I think anchor links are a really important feature for a mostly-text website like this one. I used pandoc because it gave me accessibility by producing vanilla HTML instead of using javascript or especially a JS framework. That said, I looked and looked for a native pandoc feature that would generate anchor links for each header and just couldn’t find one. I noticed that pandoc’s own manual is generated with pandoc, and it has anchor links, but best I can tell they use a custom Haskell plugin to do that. I also found the following links to google groups discussions of people trying to do the same thing.

Since anchor links already aren’t going to be as useful to a browser like lynx or a screen reader, I figured it would be an okay shortcut to use javascript for these, which I did by just adding it to the template.

This website is a work in progress. If you have any thoughts about this feel free to share on the repo (you can find the link to the source of any page in the footer)!