~jisifu

notebook · envs.net
no framework, no fonts

post3 minpublishingbuildmarkdownmeasurement

What a page costs

This site used to be built by a Nushell procedure in one directory and a PHP script on another machine. Both worked. Neither ran, because each lived on the host that served the result, and the result was the only thing anyone looked at.

So the build moved next to the source, where it can fail in front of you.

source files 1 corpus of markdown
pages emitted 57
build time, cold, one process 0.60 s
assertions 11, hard
links checked 106
shared CSS + JS 19.8 KiB raw, 6.2 KiB gzipped, cached once
per-page budget 14 KiB, enforced

The pipeline#

build.sh finds comrak and runs build.py. That is the whole dependency list: Python’s standard library, and one markdown renderer. build.py reads src/pages/*.md, src/posts/*.md and src/notes/*.md, renders each body with comrak (--unsafe, so a page may hold a canvas when the page is about a canvas), wraps it in one template, and writes public/.

text.py does the second job: the same markdown becomes gemtext, gopher menus and the finger .plan. It is a converter with opinions — a table becomes one line per row, emphasis disappears, a link moves to a line of its own — because that is what the protocols allow, and hiding the loss would mean the page was written for the web first.

No framework, no incremental cache, no plugin API. A full rebuild is 0.60 s, so the honest answer to “why not incremental” is that it would cost more to maintain than it saves.

The gates#

Eleven assertions run after the pages are written, and an assertion here is a broken build, not a warning:

  • routes are unique, and only the home page has no h1
  • every other page has exactly one h1
  • dates are ISO, and no page is dated in the future
  • no unrendered markdown survives into the HTML
  • every post has all three mirrors (gemtext, gopher, finger plan)
  • the capsule root and the gophermap are written from src/capsule.md
  • the page budget holds, page by page

The dead-link walk is separate because it costs the most: it parses every emitted page and resolves every internal href against the routes that exist. One hundred and six links, one second of patience, and a redesign that silently orphans a page fails before it is published.

The verdicts are also written to public/build-report.json — each assertion with its detail, and every page with its raw and gzipped size. That file exists for the builder that comes next: a Nix derivation can enforce the same rules without re-deriving them from HTML, which keeps the rules in one place while the implementation changes.

What one page actually costs#

A post is text plus one template. The shared stylesheet and the small navigation script are 6.2 KiB gzipped for the entire site and are fetched once.

The expensive pages are the ones with a demo. /lab/ is about 6 KiB of HTML, plus a 6.8 KiB script, plus a 512-byte wasm module for the Mandelbrot kernel and a 213-byte module for the 8 MiB fold. That is still less than one screenshot, which is the comparison worth making rather than the one against other sites.

Why Python, and why not forever#

Python is the prototyping surface: it compiles markdown, applies rules and prints verdicts with no ceremony, and this whole builder is under a thousand lines. It is also a second language in a fleet that already has a Nix compiler and a task plane, so the end state is a Nix builder that enforces the same assertions from the same report.

Building it in that order is deliberate. The rules were easier to discover as code that could be wrong in public than as a module that has to be designed first: the hard gates came from pages that actually broke, not from a specification.

Until then the contract is simple. src/ is the only thing you edit, public/ is never committed, and ./build.sh --strict is the question “would this publish?” answered in under a second.