Building this site with an agent

2026-07-17T00:00:00+00:00
This site serves the same page four ways. A browser gets HTML. curl</code> gets ANSI-coloured text. ?format=md</code> gets the Markdown source, ?format=json</code> gets structured data. One URL, one build, four representations.</p>
I built it in a session with Claude Code. This is what actually happened, including the parts that went badly, because the interesting content is in the failures rather than the result.</p>
The design decision that mattered</h2>
The obvious approach is to render each format from the Markdown source. Zola already turns
Markdown into HTML, so add a second renderer for ANSI and you are done.</p>
That is wrong here, and it took a correction to see why. The body Markdown is not the page.
title</code> and description</code> live in front matter and get assembled by the templates. Feed
content/_index.md</code> straight to a renderer and you get output starting mid-sentence, with
no heading and no description. The template owns the composition, so anything that skips
the template renders something the site never publishes.</p>
So the built HTML is the single source, and every other format derives from it:</p>
content/*.md ──(zola)──> public/**/index.html</span></span>
                           ├─(pandoc)──(glow)──> index.ansi</span></span>
                           └─(glow --style notty)──> index.txt</span></span>
content/*.md ──(front matter stripped)────────────> index.md</span></span></code></pre>
Markdown is the deliberate exception. It is copied from source rather than converted back
out of HTML, because the source is the real thing and a round-trip would be a lossy
reconstruction of something already on disk.</p>
This is the same trick style.ysap.sh</a> uses, inverted. That site
renders Markdown to ANSI first and derives its HTML from the ANSI, so the formats cannot
disagree. It also means its HTML is</em> terminal-shaped, which is the point there and not
here. Same guarantee, opposite direction: one rendering pass, everything else a transform.</p>
Colour, and why the palette is not mine to choose</h2>
curl style.ysap.sh</code> looks better than this site does in a terminal. It is worth being
precise about why.</p>
That site emits 1254 absolute 256-colour codes and 20 background colours. The logo is
48;5;223</code> — a hardcoded cream background. It looks great on a dark terminal and it does
not care what theme you use, because it brought its own. To replay that in a browser it
ships 1118 lines of CSS mapping the 256-colour palette to classes.</p>
The alternative is to use only the 16 base colours. Those are not colours. They are slots.
\e[35m</code> means “slot 5”, and the terminal decides what that is — which is what a theme
mostly is</em>. Nord renders slot 5 as #B48EAD</code>, Rose Pine as #C4A7E7</code>, Solarized Light as
#d33682</code>. Emit slot numbers, never set a background, and the page renders natively in
whatever theme the reader already chose. On a light terminal it stays readable, without
guessing.</p>
The cost is real. Sixteen slots and no backgrounds cannot draw that logo. The site is
plainer than it could be. In exchange it does not fight anyone’s colour scheme, and the
choice belongs to the reader rather than to me.</p>
The semantics are still mine — headings magenta, links cyan, URLs dimmed — but they are
expressed as slots, so the mapping to actual pixels happens in the terminal, after I am
done.</p>
What went wrong</h2>
The rendering tool silently dropped every colour.</strong> glow v2 emits \e[;1m</code> — bold, with
an empty colour slot. Its own shipped styles do the same, so it is not a problem with our
style. glamour v2 moved to lipgloss v2, where lipgloss.Color</code> no longer resolves numeric
strings like "5"</code> or "252"</code>, and every numeric colour quietly becomes nothing. The fix
was pinning glow to 1.x, capping Renovate below 2.0.0, and opening an issue so the pin has
an exit rather than rotting.</p>
Local verification tested the wrong binaries, three times.</strong> The local glow was a source
build of unknown version and rendered correctly. The container pinned v2 and did not.
Alpine ships pandoc 0.1.1.1, which left the page navigation in the ANSI output; the local
pandoc was 3.10 and stripped it. Then CI tested a stale image, because the service pulled a
mutable tag and the runner reused a cached copy. Three separate bugs, one cause: “verified
locally” meant a different artifact than the one shipping. The fix is boring — pin every
tool version in mise.toml</code> and</em> the image, and test a pod built from the real image.</p>
The tests passed on visibly broken output.</strong> At one point the page rendered entirely in
one grey. The suite went 15/15 green, because it asserted “has escape codes” and “only uses
base-16” — both true of garbage. Tests that check the shape of the output rather than
whether it is right will confirm whatever you give them. Three assertions fixed it: no
empty colour slots, headings styled distinctly from body, more than one colour present.</p>
The linter caught a bug in the tests.</strong> shellcheck flagged SC2314: in bats, !</code> does not
fail a test unless it is the last command. Four negative assertions had been passing
unconditionally. Then the fix repeated the mistake — run ! head file | grep</code> applies to
head</code>, not the pipeline.</p>
One CSS-shaped detail took three attempts.</strong> ?format=md</code> returned
application/octet-stream</code>, because nginx try_files</code> serves a file without re-running
location matching, and .md</code> is not in mime.types</code>. default_type text/plain</code> fixed it,
and deleting three now-dead location</code> blocks came with it. Later a types</code> block gave each
representation an honest content type — text/markdown</code>, text/plain+ansi</code> — after checking
that a types</code> block merges with mime.types</code> rather than replacing it and quietly breaking
CSS.</p>
On working with an agent</h2>
The agent was fast at the mechanical work: scaffolding the chart, wiring nginx, writing the
bats suite, reading upstream source to find the lipgloss regression. That part is real and
it is not a small saving.</p>
It was also confidently wrong on a regular basis. It diagnosed a Kafka crashloop as a
read-only filesystem problem when an identical StatefulSet ran fine on the other cluster.
It blamed TERM</code> for the missing colours and was wrong twice before finding the version
mismatch. It told me to delete a PVC to wipe corrupt data on a storage class that
provisions by name and retains on delete, so the delete was a no-op and the corruption came
straight back — a fact documented in a comment in my own repo that it had read hours
earlier.</p>
The pattern is consistent: it stops at the first plausible cause, and the first plausible
cause is often wrong. What broke that pattern was comparing against something known-good —
the other cluster, the other glow version, the same style on both binaries. Not more
reasoning. A reference point.</p>
The useful division was: it does the work and holds the context, I decide what is true.
Every real correction in this session came from pushing back — the source-of-truth
inversion, the terminal-theme objection, running the thing in a real pod instead of
trusting a local run. The agent implemented all of those well. It proposed none of them.</p>
It also wrote a first version of this page full of the phrases you would expect. That
needed removing too.</p>
Where it landed</h2>
Four formats, one build, no backend. The negotiation is a map</code> on the user agent, with
?format=</code> as a deterministic override, because sniffing is a heuristic that breaks on
bots, HTTPie, and curl | less</code>. Every file stays reachable directly. The container runs
nginx unprivileged on a read-only root filesystem. Eighteen tests run against the built
image in CI.</p>
The plain version is one query parameter away, for anyone whose terminal disagrees with all
of this.</p>
ptrck.sh

Building this site with an agent

Hello, world
