Front matter that the index depends on
Dates, subjects, permanent citation handles and the fields that connect published work.
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.
archives builds the date index. It is not derived from date — the
three-element year / month / day form has to be written out, and the
archetype does it automatically. Wrong here means the entry is missing from
/archives/ while looking fine on its own page.
resolves + aliases are the citation handle. Assigned once, never
renumbered, resolving at /r/<code>/ forever. Two entries claiming the same
number is a silent collision — one alias wins and the other is lost.
story.sh plan assigns the next free handle by scanning the existing entries,
which is the reason to use it rather than copying an old entry’s front matter
and editing the number by hand. It also refuses to publish an entry with no
tags, because that entry would render and appear in no index.
The optional ones worth using
description = 'One sentence. Used for meta description and search results.'
claim = 'One line. Renders as the standout paragraph under the date.'
Images, in a bundle
[[resources]]
src = "screenshot.png"
title = "Screenshot"
[resources.params]
alt = "What is actually in the image, for a reader who cannot see it."
caption = "Rendered under the figure."
credit = "Screenshot"
alt is not optional. The theme prints caption and credit beneath the
figure and uses alt on the image itself.
Journal and Lab Notes
Journal remains content/posts/: complete, authored pieces, with existing
URLs and JRN handles unchanged. A Lab Note is a bundle at
content/lab-notes/<slug>/index.md, with draft = true to start. Its stable
URL is /lab-notes/<slug>/; use a descriptive heading such as ## Finding
to give a Journal article an anchor it can cite.
title = 'A useful observation'
date = 2026-11-20T10:30:00-06:00
draft = true
description = 'A short account of what changed or what remains uncertain.'
tags = ['hugo', 'workflow']
projects = ['jwogrady-com']
archives = ['2026', '2026-11', '2026-11-20']
related = ['/docs/publishing', '/posts/personal-brand-first']
projects is a shared taxonomy, not an instruction to move old articles.
related names page paths or existing citation handles. It produces links
and backlinks only to pages present in the build: a public article must not
reveal a private note’s title. Publish a cited note before linking to it from
a public article.
Use the cite shortcode for a checked cross-reference:
{{< cite "JRN 26-018" >}}
{{< cite "/lab-notes/a-useful-observation#finding" "the experiment" >}}
The build fails if that target is absent, including when it is still a local draft. Ordinary Markdown links still work, but cannot provide this check.
Docs previews and downloads
description = 'A short explanation of what this document helps with.'
preview = 'cover.png' # bundle resource, assets/ resource, or another page's resource path
format = 'HTML' # label; omit for an ordinary web document
lastmod = 2026-11-20 # only when the document was actually revised
# download = '/documents/checklist.pdf' # optional; never inferred
An entry can be a web page, a downloadable file, or a web page with a download. The index always opens the page and shows the download separately. A preview is an aid to recognition beside the same title, so it has empty alt text rather than repeating the link to a screen reader. Content images still need meaningful alt text. Missing previews use a labelled document plate; SVGs and unsupported formats do not enter the raster processing path.