Website Theme Update and Release

I know I just said in the last post that my website theme was tightly coupled to my website and poorly architected, but I decided to take a stab at decoupling them since the base theme, astro-erudite⁠ got a very handsome v2. So this time, in my unofficial series of website theming update posts, I thought I’d explain what has changed, then explain how I went about doing it.

My website source is still private since I have some drafts and other private information, but you can find my website theme in the appropriately named website-theme⁠ repo. Note that that repo is entirely LLM written, though the general design was mine.

What has Changed

1. Swap to astro-erudite v2. This is a big change, and I like the v2 layout a lot. The theme also swapped to Satteri instead of rehype for extensions, so I swapped some deps and rewrote my bibliography dep and a few other things.
2. Build-time justification using justice⁠. I was using justif⁠ before which was very nice, but I try to minimize clientside JS as much as possible, as a matter of principle, and ran into justice. I was making large changes with the v2 rewrite anyway so decided to throw this in. Also, phones and other small devices are now ragged right instead of justified.
3. Side notes¹ instead of footnotes on wide displays, since these read better I think. I sometimes have dense, long footnotes which don’t look the best stacked (again, see the last post) as the referent moves further and further away from the actual note, but I think they look better than footnotes on the whole.
4. Lists for mini-reviews and such like books.
5. Citations get hover previews.
6. Added a few pages.
7. Assorted performance changes.

So not much on my end which is user facing, with a ton of cool improvements⁠ from upstream’s v2 which materially improve the readability of the site.

Public Theme

As mentioned, my new theme is now public⁠, albeit without my brand colours or fonts or whatever. All that is configured through a central theme.json, allowing for all the structural and functional changes I make to be visible without it being completely trivial to copy my site’s look.

Compared to astro-erudite, I added:

1. Pagefind⁠ search
2. Build time justification via justice⁠
3. Build time font subsetting with fonttools⁠
4. Citations with pandoc semantics using citation.js⁠
5. Structured lists (ledgers), see pages in the library
6. Dropcaps
7. Side notes

The way the theme repo is structured is a little strange but I like the idea. astro-erudite is added as a submodule, and my theme is layered atop it—with Astro’s lookup searching in root before resolving to the submodule for anything I don’t overwrite. The design of the site (colours, typography, etc.) is controlled through the aforementioned theme.json which is meant to somewhat evoke Posit’s brand.yml⁠ which is the canonical reference for my theme.

My theme deviates from upstream in a few ways too, like removing navigation buttons completely, removing authors, and not rendering subposts as a continuous whole.

How?

I’m sure everyone is dying to know how I pulled this feat off after saying content and theming were tightly coupled in the previous post. I used Sonnet 5.5 to swap to astro-erudite v2 in one large and unwieldy PR on my site, and I tested this version until I was happy with how everything looked and performed. Once I had that, I told it to send out an Opus 5.5 subagent to work in another repo and port all the theming, then to stack a branch on my v2 branch which swapped to my theme. Building the theme out first was necessary since then the Sonnet agent working on my website could verify the theme was implemented properly by ensuring the stacked branch matched its ancestor, so that the differences were all semantics. This is essentially identical (but more thorough since the HTML files could be directly compared) to snapshots, but I ran out of free GHA minutes this month due to this and some other projects (which was also strong motivation for splitting out theming into a public repo).

I had fixed submodule layout though, and didn’t think any LLM objections were strong enough to heed, and I think that was an important design decision. I want future astro-erudite updates to be very easy to merge, which the submodule structure easily allows (with weekly dependabot checks). A release CI flattens the module out so it can be used as a proper dependency.

This was pretty easy once I thought about the design a little, and I think it turned out okay. I’m primarily going to be developing the theme for myself, but it’s nice to have it public in case anyone finds it useful.

Footnotes

1. Which look like this! ↩︎