hugo on jwogrady

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.

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:

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.

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.

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.