I first heard about the idea of a /colophon page from Slash Pages. I was not familiar with this concept, but apparently that is the term used to define the section of a printed work that describes the publisher and/or publishing process. We can of course adopt this to web pages, describing the development process and technologies involved.

I have had many iterations of this site over the years, but most of them have been based on GitHub Pages. This is an offering by GitHub where you get a free personal static website at a URL matching your username. It is incredibly easy to use and is a perfect fit for a simple purpose like a personal blog.

I originally started with artisanal, hand-written HTML. This was about as painful to maintain as you might guess. After a few years of that I migrated over to Hugo (I was going through a bit of a phase with Go). This served me reasonably well, but I was always a little uneasy with the seemingly perpetual v0 nature of the project. This did not directly impact me at first though, so I put those concerns to the side. But after a while I got a new laptop and when I was setting up my development environment I realized I was about 100 minor versions behind. When I finally upgraded Hugo it broke my site in a dozen tiny ways, and I decided it was time to revisit this project. I had been playing with the idea of my own static site generator for some time and this was the moment that pushed me over the edge.

I had heard of Pandoc before and was interested in trying it out but never had a compelling use-case. I thought this was an interesting idea: use Pandoc to hand-roll a static site generator. I always felt like Hugo had just a few too many bells and whistles for my needs. To complete this migration though I needed to nail down my core requirements:

After a bit of testing I landed on 3 scripts:

  1. build.ps1: Pulls together the .md files in the source repo and converts them to index.html files in corresponding directories via Pandoc. Note: generating /slug/index.html allows you to use example.com/slug/ as your URL rather than example.com/slug.html.
  2. serve.ps1: A simple helper script to run a local web server to test your changes as you go.
  3. deploy.ps1: Run a build and then copy over the latest .html and asset files from /public/ to a sibling GitHub Pages repo, then push that to master.

And there you have it, a very simple static site built with Pandoc!