BHDicaire

Section archetypes

Each archetype below defines what a kind of section is — what it is for, what belongs in it, what does not, and its operating rules — independent of any single site, so a new site (personal, consulting, open source) can adopt one without deciding it again.

Blog#

For: essays, announcements, records of a position at a particular moment — and technical notes maintained as living documents.

Traditional blogs are linear: new posts on top, older posts sinking into the archive, each entry a polished final draft. That model still fits essays, announcements, and snapshots of belief. It does not fit every page: some notes behave more like a digital garden, where an idea starts as a seed, gathers links, becomes a TIL entry, grows into a blog post, and sometimes turns into a collection. That model rejects performative polish in favour of showing work while it is still developing.

Operating rules for living documents:

  • A technical note should not pretend to be final. Defaults change, tools change, threat models change; the right posture one year may need pruning two years later.
  • Make both dates visible. Created is when the note first became public; Updated is when the substance last changed. Front matter carries both date and lastmod: the creation date keeps provenance, the updated date tells readers whether the page is still being cared for.
  • Quiet edits only bump lastmod. Fixing a typo, improving a sentence, or adding one reference needs no ceremony.
  • Add a change log when the reader may care what changed: a security recommendation changed, a command or configuration was replaced, the page now recommends a different tool, or old advice was removed because it became unsafe, misleading, or obsolete. In those cases the page should not hide its evolution — the change log is part of the trust model.
  • Evergreen does not mean static. A truly evergreen page stays useful because it can be revisited, corrected, expanded, and occasionally cut back. Add a link when the source is small, write a TIL when the lesson is self-contained, grow it into a blog post when it needs context, turn it into a collection when the idea becomes a small map.

A blog can be evergreen if it stops pretending every post is a sealed artifact. Some pages should remain essays; others should be maintained gardens — dated, updated, linked, and allowed to grow in public.

TIL (Today I Learned)#

For: small learnings that do not deserve the ceremony of a full blog post. A public notebook, not a polished article archive.

The format is intentionally small: one thing, a few lines, enough context for a future reader to understand why it mattered. Entries capture the things learned while building systems, debugging deployments, reading docs, or trying tools — the exact command, flag, error message, setting, or mental model that will otherwise be forgotten in three months.

  • Belongs: anything self-contained and too small for a full post. The publishing bar is deliberately lower than the blog’s, so small revelations get documented instead of lost.
  • Does not belong: anything that needs real context — that grows into a blog post instead.
  • Messy is acceptable. A useful note today beats a perfect essay never written.
  • Recent notes first, browsable later — practical enough to serve as a memory extension.

The pattern comes from Julia Evans’s TIL microblog and Simon Willison’s TIL site.

Collection#

For: grouping related posts that belong together without deserving a new top-level section — for example, a running record of decisions about one topic.

The mechanism is a single front matter key:

collection: "hugo"

The single-post layout checks for that value. When it exists, Hugo finds the other regular posts with the same collection, sorts them by date, and renders a compact list below the article. The current page is marked with aria-current="page" so the list is also useful to assistive technology.

  • Posts stay ordinary posts at stable URLs; the collection changes nothing about the URL model.
  • The collection is just metadata until a template decides to use it — no custom content type, parallel taxonomy, or special layout per series.
  • A folder is not a series. A subdirectory can make the repository easier to scan, but it does not create a semantic series; the pages still belong to their section.
  • Promote only when it grows. A collection that becomes something larger can graduate to a dedicated section, a landing page, or a manually edited guide. Starting with front matter keeps URLs durable and maintenance low.

The rule: use a collection when posts should be read together but should still behave like ordinary posts.

Now / Then#

For: answering the question a friend would ask when catching up — what has your attention these days?

The Now page, an idea from Derek Sivers’s nownownow.com, is a small status report: what is being built, what is being learned, what is taking energy, what is on pause. It is not a biography, not a resume, not a press kit, and not a social feed.

The Then page is the companion piece. A Now page is useful in the present, but its older versions become a quiet archive of priorities over time: current work up front, older snapshots moved into the Then archive, kept scannable as it grows (accordions work well).

The point is not to document every life detail — it is to leave enough context for friends, collaborators, and a future self to understand what season this was.

Colophon#

For: stating what the site is made of and why. In a book, a colophon describes the type, printer, paper, and production details; on a website, it explains the stack, the hosting, the fonts, the analytics choices, and the values that shaped the build.

  • Not just a parts list. A colophon is a compact statement of principles: choices such as avoiding client-side tracking, self-hosting fonts, publishing in two languages, or preferring plain Markdown and data files over hidden systems should be visible somewhere.
  • Pair it with humans.txt — a small, legible web convention that says who made a thing and what it is made from.
  • Drive recurring pages from shared data. The now, uses, colophon, and humans.txt pages can share structured YAML data, which keeps the site maintainable in two languages without turning every content update into a template edit.

Wiki#

For: a single-user reference of densely interlinked topic pages — organized by subject, not chronology. A static site generator suffices: no separate authors, no page revisions, no database server.

The defining requirements:

  • Free forward links. While writing a page, link to topic pages that will exist in the future without worrying whether they exist right now.
  • Visible missing links. A link to a page that does not exist yet is styled distinctly (for example, red instead of blue) and updates automatically once the page is created.
  • A common “coming soon” page. Missing links land on one placeholder page rather than a 404; normal site 404 behaviour is untouched.
  • Plain Markdown authoring, including code syntax highlighting.

The Hugo mechanics, adapted from Justin Miller’s “Repurposing Hugo as a wiki”:

Enable inline HTML in shortcodes and make unresolvable references non-fatal, routed to the common missing page:

markup:
  goldmark:
    renderer:
      unsafe: true

refLinksErrorLevel: WARNING
refLinksNotFoundURL: /pages/missing/

A link shortcode takes one argument when the page slug matches the clickable word, two when the link text differs:

{{% link other %}}
{{% link "my text here" other2 %}}

The shortcode itself, layouts/shortcodes/link.html:

{{- $link := (urls.RelRef . (cond (eq (len .Params) 2) (.Get 1) (.Get 0))) -}}
<a href="{{ $link }}"{{ if eq $link (urls.RelRef . "missing") }} class="missing"{{ end }}>{{ .Get 0 }}</a>

Because it resolves through urls.RelRef, links are filename- and reorganization-independent: an argument of other finds other.md, or any file whose front matter sets slug: other, wherever it moves. When resolution fails, the missing page is linked and the missing CSS class is applied:

main#content a.missing {
  color: #f00;
}

One known wart: the missing name is duplicated between the shortcode and the site configuration, because no Hugo function exposes the configured refLinksNotFoundURL value.