Colophon: Experiments in Static Site Generation
Colophon is a very experimental static site generator built atop the Racket programming language and the Pollen publishing system.
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.
Recent
A Wishlist
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).
Basic Syntax Highlighting
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.
Dependency Management
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
changed (the posts/index.html is rebuilt when the
posts/index.html.pm file is changed.
Extracting Reusable Code
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
in the 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.
Key Principles and Features
Here are some thoughts on principles guiding the development of Colophon and the features they imply.
Themes and Templates
With the most recent refactoring, Colophon has a basic, but functional theming system. Since Colophon is a system for building websites, themes are written as CSS (though in the future themes could be written in something like CSS-expressions).