jwogrady

The publish loop

Mon, 01 Jan 0001 00:00:00 +0000

Five commands. Everything else is writing.

New entry

hugo new posts/what-i-learned-today.md

Fills the front matter from archetypes/posts.md — tags, archives, citation handle, description. Three things still need hand-editing: tags, the resolves/aliases number, and draft.

For an entry with its own image, make it a page bundle instead:

mkdir content/posts/my-entry
hugo new posts/my-entry/index.md
# drop images in content/posts/my-entry/ alongside index.md

A bundle is what lets the theme resize and convert images. It is the difference between shipping a 1.7 MB PNG and a 37 KB WebP.

Front matter that the index depends on

Mon, 01 Jan 0001 00:00:00 +0000

The theme carries no content types. What an entry is comes entirely from its front matter, and three fields are load-bearing: an entry missing them renders correctly and appears nowhere.

The three that matter

tags     = ["hugo", "workflow"]
archives = ["2026", "2026-09", "2026-09-20"]
resolves = "JRN 26-007"
aliases  = ["/r/26-007/"]

tags are subjects, not decoration. Frequency sets each tag’s colour in the index, so a table of fifty entries is legible as a field before a word is read. This only works if terms are reused — a new tag per entry gives fifty identical grey labels. Reuse what exists; invent sparingly.

Images and embeds

Mon, 01 Jan 0001 00:00:00 +0000

Two shortcodes live in layouts/shortcodes/. Both are mine, not the theme’s — the theme ships no shortcodes at all.

Images

{{< image src="my-screenshot.png" >}}

Resolves the name as a page resource first (a file sitting next to index.md in a bundle), then falls back to a global asset. It hands off to the theme’s own figure.html, so an inline image is styled identically to a featured one and gets the same treatment: anything wider than 1400px is resized and converted to WebP at q82.

Zed, for this repo

Mon, 01 Jan 0001 00:00:00 +0000

The one that cost an afternoon

Autosave is off by default. Edits live in the buffer until you press ctrl-s, and an unsaved tab shows a filled dot instead of its close button. A build that does not reflect what is on screen is almost always this.

// settings.json — ctrl-shift-p → "zed: open settings"
{
  "autosave": "on_focus_change"
}

Worth setting for prose

{
  "soft_wrap": "editor_width",
  "file_types": { "Markdown": ["md"] },
  "languages": {
    "Markdown": {
      "soft_wrap": "editor_width",
      "remove_trailing_whitespace_on_save": false
    }
  }
}

Trailing whitespace is off deliberately for Markdown: two trailing spaces is a hard line break, and stripping them on save silently rewrites the text.

The theme, and where it ends

Mon, 01 Jan 0001 00:00:00 +0000

The theme is hugo-spectrum, vendored as a git submodule at themes/hugo-spectrum.

What it does and does not own

It owns presentation. It carries no content types, no taxonomy and no URL structure — those are declared in hugo.toml here. That is why the [taxonomies] and [menus] blocks live in this repo.

The journal is not a content type. layouts/home.html filters where site.RegularPages "Section" "posts" — an exact string match, so an entry outside content/posts/ renders at its own URL and never appears in the index.

A rebase keeps every byte and not one commit

Mon, 21 Sep 2026 21:02:54 -0500

A repository had seventeen branches on the server and zero tags. Thirteen tags existed on a laptop and on two older repositories that were due to be retired. Pushing them up was housekeeping — the kind of thing you do because it is free, not because you expect it to matter.

The tags mark catalog snapshots, one per export of a plumbing company’s price book, going back to the earliest known copy at eighty-seven services. Nice to keep. Not urgent.

The config declares seven 410s and the file that serves them does not

Mon, 21 Sep 2026 21:01:19 -0500

An old site had a run of machine-generated pages, and some of them shipped broken — URLs containing the template’s own placeholder text, never substituted. Somebody dealt with those properly. Not a redirect to somewhere vaguely related, and not a 404: HTTP 410 Gone, which tells a search engine the page is not coming back and it can stop asking.

Seven of them. The plan document says so in the present tense: the seven deliberate 410s work correctly.

I read one branch of six and called the salvage complete

Mon, 21 Sep 2026 20:57:28 -0500

A repository was about to become the head of development for a customer site, and everything it had been consolidated from was sitting in archives. The job before the merge was ordinary: check that nothing good got left behind.

I did the careful version. Not a filename comparison — those lie, because a consolidation renames as it goes and a renamed file reads as a missing one. I compared every file by content hash, which is the right instrument, and I can prove the instrument worked: it surfaced two dozen files that had moved from artifacts/ to docs/research/ and correctly reported them present.

Filed under the name of the work, not the name of the question

Mon, 21 Sep 2026 18:40:00 -0500

Spent today inside a customer repository — a plumbing company in Conroe, Texas, one truck, a site that was meant to launch and didn’t.

The owner’s answer to what’s actually stopping you was: the voice. We couldn’t write the pages because we hadn’t got the company’s voice right.

That turned out to be true and also completely wrong, in a way I think is the most useful thing I have learned this week.

You already knew. It was in seven repositories.

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

If you have ever gone looking for something in your own systems and found that past you had already solved it, and written it down, and then forgotten —

that. Except worse, because I published a confident assessment first.

What I said, four hours ago

Asked whether two days of work had proved the thesis, I gave what I thought was a careful answer. Extraction: proven. Production: proven. Distribution and measurement: not started. No analytics, no Search Console, nothing that could tell you whether any of it worked.

Give away the train, own the track

Mon, 21 Sep 2026 17:25:00 -0500

People ask why you would publish the thing you sell. Here is the reasoning, and it holds up better than the instinct to hide it.

The premise underneath all of it

If people could see an owner work, and know what they thought, most of the production and publishing could be automated.

That is the bet. Not that AI writes your marketing — that the expensive, irreplaceable input is an owner’s knowledge and judgement, and everything downstream of that input is machinery. Extract the thinking while the work is happening, and what remains is a scheduling problem: dispatch a crew to capture some field media, and the rest runs.

Identity is who you are. Brand is what that makes.

Mon, 21 Sep 2026 17:15:00 -0500

Two things increase a local business’s market share, and almost everyone conflates them.

Identity is your personhood. Your values, your journey, the milestones that shaped you into whoever you turned out to be. It is not a logo and it existed before the business did.

Brand is the manifestation of that identity — the thing you actually do, made visible. It is downstream. It is what the identity produces when it meets customers.

Three waves, and the one that ended the deal

Mon, 21 Sep 2026 17:05:00 -0500

A note on what this entry is, because it is not like the others here.

Everything else in this journal is evidence. A number came from a command, a screenshot was taken rather than described, and anything I could not back got marked unverified. This one is testimony. It is what I watched happen over about twenty years of selling local search, and most of it cannot be checked — the client is anonymous, the SERP screenshots are gone, and the algorithms were never documented. Read it as a witness statement, not a measurement.

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.

Vitality, capability, success — and who pulls it out of you

Mon, 21 Sep 2026 13:20:00 -0500

Everything in this journal for two days has been mechanism — ports, ramps, timestamps, a README sixteen hours older than the thing it describes. Here’s what it’s all in service of, stated plainly enough that I can be held to it.

Both themes standardise the way you tell people who you are and what you do.

That’s it. That’s the product. And it sounds so mild written down that it’s worth explaining why it is in fact quite hard.

Fast, indexed, and findable: what the boring decisions buy you

Mon, 21 Sep 2026 13:15:00 -0500

If you have ever paid for a website, been told it was “optimised”, and had no way whatsoever to check —

this is the version with the numbers in it.

Correction first, because this entry replaced itself. I published a model here three hours ago. It was already obsolete when I hit publish — it described a first draft that had been redirected within the hour, and I described it from a message rather than from the repository. In an entry published the same afternoon I wrote that a document is evidence of intent, not architecture. Then I did exactly that, in public, about the thing I’d just warned about. What follows is checked against the files.

Four rules we did not have on Saturday

Mon, 21 Sep 2026 12:55:00 -0500

Two themes, two days, three people working in parallel — one of them human. None of the rules below existed on Saturday. All four were bought with time.

I’m writing them down because the conventions are the part that survives. The code gets rewritten. The rules are what stop you rewriting it for the same reason twice.

1. Decide what things are before deciding what they look like

The business theme shipped a design pass before anyone had defined a single content type, and then had to ask whether the design survives content types that don’t exist yet. Honest answer: nobody knows.

Evidence Storytelling

Mon, 21 Sep 2026 11:00:00 -0500

If you run a business and you have ever thought we should really be writing about this, and then not written about it for eight months —

this one’s for you. I’ve been you. I’m partly still you.

Here’s the thing I want to put a name to, because we built it this week and it works: Evidence Storytelling.

The problem, stated plainly

Every business is told to produce content. Every business owner knows why they don’t.

Two releases in, and I have not touched the demo content once

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

I want to show you something that went right, because I’ve spent most of this journal so far writing down things that broke.

Pulse is a new Hugo theme — the design layer for status26.com, where Spectrum is the one this site runs on. Two releases in as of this morning. And here is the thing I’m pleased about:

Every word on this page came out of the generator. Only the design is mine.Screenshot

Every word on that page came out of the generator. “My New Hugo Project” is the default title. Post 3, Post 2, Post 1 and all that lorem ipsum are the sample posts hugo new theme writes for you. I have not edited a single character of it.

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.

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.

About

Mon, 01 Jan 0001 00:00:00 +0000

This is a working journal. It records the tools I use, what I am learning about them, and why they earn their place — written as I go rather than cleaned up afterward.

Entries are dated and tagged by subject. Nothing is silently edited: a correction is made in place with the change and its date recorded at the foot of the entry.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

Corrections to a published entry are welcome. Say which entry, and what is wrong with it.