spectrum on jwogrady

The fix that deletes its own evidence

Mon, 21 Sep 2026 16:30:00 -0500

If you have ever fixed something, watched the test go green, and had a small unplaceable feeling that the green was too easy —

hold that. It’s the good instinct and this entry is about the mechanism behind it.

What happened

Earlier today I reviewed a release of the theme this site runs on. One of its features: when an entry has no claim — the short assertive line that shows under a title in the index — fall back to the description rather than leaving the row bare.

Four releases for the person before the business had one

Mon, 21 Sep 2026 10:45:00 -0500

If you have ever gone back to something you wrote a few weeks ago about your own plan, and found it describing a plan you no longer have —

yes. That one. Let’s talk about that.

What I would have told you yesterday

I have two Hugo themes. A theme, if you haven’t met one, is the design layer: it decides what a page looks like and leaves the writing alone.

The feature I chose the theme for does not work on one post

Sun, 20 Sep 2026 16:57:00 -0500

The index colours every subject by how often it’s used, so a table of fifty entries is legible as a field before you’ve read a word of it. That’s why I picked this theme.

With one post and three tags it rendered flat grey, and I assumed I’d misconfigured something.

I hadn’t. Reading the partial explained it in about four lines:

{{ $counts := slice }}   {{/* distinct counts, ascending */}}
{{ $bands := len $counts }}
{{ $hue := div (mul (mul 2.0 $span) (float $b)) (float $bands) }}

One band per distinct count — not per tag. Hue is the band’s index spread around the wheel, and the top band goes white. Three tags used once each is one band: one hue, and it’s the apex, so it’s white. Nothing was broken. There was simply nothing to distinguish.

A theme that refuses to build, and why I came around to it

Sun, 20 Sep 2026 16:46:00 -0500

The theme hard-fails with no timeZone in config. Not a warning — a failed build, on a line I hadn’t written yet.

My first reaction was irritation, and I want to record that honestly, because I’ve been on the other side of this argument. A library that refuses to start over a missing config line is infuriating in the moment.

Then I worked out what it’s preventing. Unset, Hugo uses the build machine’s zone. An entry filed at 00:17 UTC is September 20 on a CI runner and September 19 on my laptop. The same commit produces two different sites, and an entry gets filed under a day its own archive page doesn’t cover.

I installed the theme and the theme did not appear

Sun, 20 Sep 2026 16:42:00 -0500

$ git submodule add https://github.com/jwogrady/hugo-spectrum themes/hugo-spectrum

Submodule rather than Hugo Modules, because Modules wants a go.mod and this theme doesn’t ship one. The submodule pins a commit, which means a checkout a year from now builds the same site as today. I like that property a lot.

Then I rebuilt and got my own handmade templates back.

The scaffold baseof.html and page.html I’d written an hour earlier were still sitting in layouts/, and a project file at the same path beats the theme’s entirely. Not merged, not layered — replaced. Five files were quietly overriding a theme I’d just installed, and the build was perfectly happy about it.

Every tutorial I can find predates the directory I need

Sun, 20 Sep 2026 16:38:00 -0500

Almost every Hugo tutorial says to put templates in layouts/_default/. Almost every Hugo tutorial is describing a structure that changed in 0.146.

Tutorials say	Actually
`layouts/_default/baseof.html`	`layouts/baseof.html`
`layouts/_default/single.html`	`layouts/page.html`
`layouts/_default/list.html`	`layouts/list.html`
`layouts/partials/`	`layouts/_partials/`

Here’s what makes this genuinely nasty rather than merely annoying: _default/ still works. Follow a three-year-old tutorial and you get a site that builds, renders and looks fine. Nothing anywhere tells you that you’ve just learned a structure on its way out.