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:
- Build and deployment of the site must all be contained in 1-2 simple scripts that will be easy to maintain. I will often take a break for several months (or years) between iterations on this site, and it might be transparent how exactly the entire process functions.
- Several of my blog posts include TeX embeddings for properly displaying mathematical equations, and any replacement should retain that feature.
- I must be able to enrich individual posts with embedded HTML and JavaScript.
- I also need support for embedded Mermaid diagrams.
- Pages must be marked as draft or ready to publish. I will often write out the skeleton of a post idea and then reject it or simply not finish it. I need to be able to store those posts within the repo without automatically publishing.
- There should be some form of tagging system. Honestly I do not use tags as heavily as I could, primarily because the volume of posts on this site is pretty low. But tags are incredibly powerful as a search/filter tool and they should be supported within this new model.
- The output format for all pages should prioritize simple semantic HTML with minimal CSS.
- (Optional) RSS feed generation. I doubt anyone actually subscribes to my current RSS feed, but I think it is good practice to build in that support early.
After a bit of testing I landed on 3 scripts:
build.ps1: Pulls together the .md files in the source repo and converts them toindex.htmlfiles in corresponding directories via Pandoc. Note: generating/slug/index.htmlallows you to useexample.com/slug/as your URL rather thanexample.com/slug.html.serve.ps1: A simple helper script to run a local web server to test your changes as you go.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!