Hugo and our Hextra fork, and no Python at all

[tannevaled]

This repository rendered a static site for an organisation whose whole argument
is that it needs no runtime but Go — using MkDocs Material and mike,
which meant a requirements.txt, a pip install and a Python setup step in
CI.

It is Hugo now, with the theme as a Go module, and there is no Python left.

The theme is our fork

require github.com/imfing/hextra v0.13.0
replace github.com/imfing/hextra => github.com/tannevaled/hextra v0.16.0

The fork keeps upstream's module path, so it is reached through a replace
rather than by importing a different path, and it is tagged independently and
ahead: v0.16.0 against upstream's v0.13.0.

This repository is the first in the fleet to consume it, so those two lines
are the pattern the others copy. The build prints hugo mod graph, so a build
that silently fell back to upstream shows in the log rather than in the
rendering. Verified here:

github.com/go-pdfkit/docs github.com/imfing/hextra@v0.13.0
  => github.com/tannevaled/hextra@v0.16.0

The thirteen pages were converted by a tool, not by hand

It checks the nav table against the tree in both directions before writing
anything — a page on disk the nav does not name, or a nav entry with no page,
is an error and nothing is written. Both refusals were exercised before the
real run:

CONTROL 1  on disk but not in the nav [orphan.md]   → exit 1
CONTROL 2  in the nav but not on disk [images.md]   → exit 1

Then it adds front matter from the nav (title, and a weight that keeps the
sidebar in the nav's order), drops a leading # Heading that only repeats the
title, rewrites the nineteen internal .md links to the sections the pages
moved into, and turns the MkDocs admonitions into Hextra callouts.

⛔ Why the output was read rather than trusted

An admonition is delimited by indentation. Rewriting only its opening line
leaves the body indented four spaces — and Markdown renders that as a code
block. The first version did exactly that, and the opening line had
converted perfectly:

{{< callout type="info" >}}
**Measured against 118 863 real files**

    Every claim on this site is measured against a corpus of real PDFs …

It is a line-by-line pass now, and the rendered HTML was checked: the body
comes out as <p> prose inside the callout, not inside a <pre>.

What is deliberately not in this change

Versioning. mike published /latest/ and a directory per version; this
publishes one current set. The fork carries a versioned-documentation kit added
on 2026-10-05, and adopting it is its own change — moving the generator and
the versioning scheme in one step would make a failure impossible to attribute.

Checks

hugo --minify builds 15 pages, actionlint passes, and git recorded the
pages as renames, so each keeps its history.

🤖 Generated with Claude Code

[tannevaled]

One thing outside the diff: Pages was still on the legacy builder

before:  build_type=legacy   source=gh-pages/
now:     build_type=workflow

mike published by pushing to gh-pages, so this repository was serving that branch. This PR publishes through upload-pages-artifact + deploy-pages, which the legacy builder ignores — merging without the switch would have left the old MkDocs site served and the new one built and never published, with every lane green.

Switched out of band, the same way go-pdfkit/app needed it:

gh api -X PUT repos/go-pdfkit/docs/pages -f build_type=workflow

⚠ The gh-pages branch is now unused. It is left alone: deleting it is a separate decision, and it is the only copy of what was published before this lands.

🤖 Generated with Claude Code