Colophon: Experiments in Static Site Generation
Colophon’s goal is to be a tool for thinking and writing, as well as for publication. This is in contrast to other static site generators like Frog, Jekyll, or Hugo, where the focus is on publication, rather than creation. Colophon is inspired by the work of Joel Dueck, epecially The Local Yarn.
Colophon currently has the following components:
Libraries providing convenience functions to write documents in Pollen. Mainly this includes functions that implement a growing subset of HTML5 tags in an intelligent, Racket-friendly manner.
Colophon itself. This is Racket code that implements features of a static site (for example, generating index pages for posts and tags). Much of this code depends on Pollen, or at least tagged X-expressions.
A website, built with Pollen and Colophon. This is an example of Colophon in action, used to test features and guide development.
A few days ago, Prof. Shriram Krishnamurthi started writing on a website using his own Racket-based website generator, including a detailed About page. I particularly liked the section about why the site is not a blog, which includes some thoughts about how he wants the site to develop. That got me thinking that I should write down what I want from Colophon. I’ll try to update this post as and when the particular features are implemented (or discarded).
One of the big reasons I’m diving into the “write your website generator” rabbit-hole is that I can have posts with nice syntax-highlighted blocks of code without onerous copy-pasting between Spacemacs and WordPress (or some other blogging platform), and with the flexbility to add better styling or other features to the code in question. So for today, we’ll try to set up syntax highlighting for code blocks in Colophon.
I’ve been gradually fleshing out parts of the Colophon system. An immediate issue that
I’ve been running into is dependency management. For example, making a change to a post
needs to trigger the related indexes to rebuild. However, Pollen as it stands doesn’t make
this easy. In particular, it rebuilds pages only when the corresponding source file has
posts/index.html is rebuilt when the
posts/index.html.pm file is changed.
After a long hiatus, I’m putting some work into Colophon again. When I left off some
months ago, I had a decently working static site generation setup, including niceties like
syntax highlighting and basic index generation. But a large part of the functionality was
pollen.rkt file for this website, not in the code for Colophon itself.
My hope is that Colophon will be usable for interesting websites in general, and that it
will be possible to get a usable starting site with a single command. So I spent a couple
of hours pulling out functionality from the website-specific code into Colophon proper.
Here are some thoughts on principles guiding the development of Colophon and the features they imply.