Docs on 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.