2026-09-20 on jwogrady

It was the keys. It was always the keys.

Sun, 20 Sep 2026 19:20:00 -0500

Last week I spent four days sorting out how we store client passwords and API keys. Four days. On password management — the single least glamorous thing on the board, the kind of task you’d hand to whoever joined most recently.

Best time I’ve spent this year, and it isn’t close.

Here’s why, and I’m going to spell it out because it took me an embarrassing number of years to see it.

A screenshot tool for a machine with no screenshot tool

Sun, 20 Sep 2026 18:58:00 -0500

Sixteen entries in and not one of them has shown anything. Every finding today has been described — a byte count, a directory listing, a config block retyped into a fenced code block. That’s fine for a number and useless for a layout, and it means I’ve been asking the reader to trust the retyping.

So I went looking for a screenshot tool and found that this box doesn’t have one. Not chromium, not playwright, not imagemagick, not scrot, not even Pillow. WSL here is a compiler and a text editor’s remote end, and nothing else.

Two config directories, and I would have edited the wrong one

Sun, 20 Sep 2026 18:52:00 -0500

I sat down to add the editor settings I’d written up in JRN 26-008 and found ~/.config/zed/ sitting there — existing, correctly named, and completely empty.

Zero files on the Linux side. Everything on the Windows side.Screenshot

Zero files. Meanwhile AppData/Roaming/Zed/ has the settings.json I’ve apparently been editing all along, and AppData/Local/Zed/extensions/installed has five extensions I don’t remember installing individually.

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.

1,784,655 bytes to 36,616, by moving one file

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

The desktop screenshot is 6664 × 2168 and 1.74 MB. It was being served at full size into a column about 672px wide. Every byte past that width was downloaded and thrown away.

What surprised me is that the fix isn’t a setting. It’s where the file lives.

From this:

content/posts/first-try.md
assets/my-virtual-desktop-setup.png

to this:

content/posts/first-try/index.md
content/posts/first-try/my-virtual-desktop-setup.png

That’s a page bundle, and inside one the image stops being a loose asset and becomes a page resource — reachable via .Page.Resources.Get, carrying its own front matter for alt text and caption and credit, and eligible for .Resize. The theme’s figure partial then does what it already does for its own images: anything over 1400px wide gets resized and converted to WebP at q82.

A page can render perfectly and exist nowhere

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

The post rendered. Right title, right date, theme styling, HTTP 200. And it appeared in no index anywhere on the site.

The theme’s home template, in full:

{{ $posts := where site.RegularPages "Section" "posts" }}

An exact string match on the section. My file was at content/first-try.md — root section, empty string, filtered out. Moving it into content/posts/ fixed it in one git mv.

Then I hit the same shape of thing one level down. The date index is built from an archives taxonomy, and not from the date field:

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.

Four editor defaults that are right for code and wrong for prose

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

Zed’s defaults are tuned for code, which is the right call and leaves four of them wrong for what I’m actually doing in here.

Autosave, for reasons recorded an entry ago and not worth reliving.

Soft wrap to editor_width — markdown has no line length, and a horizontal scrollbar inside a paragraph is a problem I inflicted on myself.

The third one is the one I’d never have guessed. Turn trailing-whitespace stripping off for markdown. Two trailing spaces is a hard line break; strip them on save and the editor silently rewrites your text, and the diff shows nothing wrong because whitespace is invisible. A formatter that is correct for every other filetype quietly corrupts this one.

The whole embed reconstructs from one string in the URL

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

Hugo ships shortcodes for YouTube, Vimeo, X, Instagram and gists. Not Spotify. So an embed is either raw HTML or something I write.

I spent a while trying to move a copied iframe around before noticing that the entire thing reconstructs from one string:

open.spotify.com/album/6mnGRO87UFiKOoHL3BezZ7?si=abc123
                 ^type ^------- the id -------^ ^tracking

That ?si= is share-tracking. It isn’t part of the address and it doesn’t belong in a published page.

Everything else — the width, the allow list, the frame border — is boilerplate I can generate. So:

Raw HTML disappears from markdown without saying anything

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

Put an iframe in a markdown file and it renders as nothing. Not a broken element, not a comment, not a warning in the build log. The element simply isn’t in the HTML, as though I’d never typed it.

Goldmark — Hugo’s markdown renderer — discards raw HTML unless you tell it otherwise:

[markup.goldmark.renderer]
  unsafe = true

I’ll defend the name. It’s site-wide and it re-enables all raw HTML in all markdown, which is a sensible thing to refuse when content might come from someone else, and a sensible thing to allow on a personal site where I wrote every file.

An editor and a filesystem can hold two different documents

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

Here’s something I didn’t know this morning: an editor and a filesystem can hold two different documents under one name, and neither is obliged to mention it.

I found out the slow way. Four rounds of “it’s not there” / “but I can see it” before I checked the only thing that settles an argument like that:

$ stat -c '%y %s bytes' content/first-try.md
2026-09-20 16:04:13 -0500  186 bytes

The editor said thirteen lines. The disk said 186 bytes.

The image was fine. The page had nowhere to be.

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

Two things were true at once and I couldn’t make them fit together.

The build was publishing my image to public/. The build was not publishing public/first-try/index.html.

I assumed one of those had to be a lie, and spent a while looking for which. Neither was. The asset pipeline and the page renderer don’t know about each other — a shortcode calling resources.Get emits its image whether or not any page renders successfully. So the image being served proved the shortcode worked and proved precisely nothing about the page.

Two folders for files that are not content, and they behave in opposite ways

Sun, 20 Sep 2026 15:45:00 -0500

Dropped a screenshot into assets/, pointed some markdown at it, got nothing. My first thought was that I’d typo’d the path. I hadn’t.

It turns out Hugo has two directories for files that aren’t content, and they’re near-opposites:

static/ is a photocopier. A file at static/x.png is served at /x.png, byte for byte, no questions asked.

assets/ isn’t published at all. It’s raw material. A file in there reaches the output only when a template pulls it through resources.Get, and then at a path Hugo picks.

Day one: the stack, and why each piece earns its place

Sun, 20 Sep 2026 15:40:00 -0500

I’m writing this one before I’ve built anything, which is deliberate. The things that are about to cost me an hour will be obvious and unmemorable in a week, and obvious-and-unmemorable is exactly the knowledge I keep having to buy twice.

So: notes while I’m inside it, not a tidy retrospective afterwards.

The stack

Hugo, because the build is one binary. No Node toolchain underneath it, nothing to npm install, nothing to rot in six months when I come back to this.

A clean build of a website that does not exist

Sun, 20 Sep 2026 15:24:00 -0500

If you have ever run the command, watched it succeed, gone to look at the thing you just made, and found absolutely nothing there —

yes. That. That’s what this is about.

Three minutes into building this site I had a perfectly clean, completely successful build of nothing at all.

$ hugo new site .
$ hugo

                  │ EN
──────────────────┼────
 Pages            │  0

Total in 41 ms
$ find public -type f
public/sitemap.xml
public/index.xml
public/tags/index.xml
public/categories/index.xml

Four files. All of them machine-readable lists of the pages on my website. All four of them describing zero pages. No actual web pages anywhere. Exit code zero, forty-one milliseconds, no errors, no warnings, no complaints of any kind.