The tools
Four scripts that generate things by hand rather than at request time, and what to run after changing what
This site has no build pipeline, and that is deliberate. Instead there are small scripts you run when you want something regenerated. Each writes plain files you can inspect, commit and revert.
The one command
There are six scripts below and the order they run in matters. Rather than remember that, run:
./tools/build-all.sh
It runs every script in the correct order, then the tests, and stops at the first failure so you are never left with a half-built site. Run it after editing anything, before pushing. Everything below explains what it is doing.
The scripts
| Command | Produces | Run it after |
|---|---|---|
./tools/build-sitemap.py | sitemap.html | Adding or removing pages |
./tools/build-kb.py | Everything under kb/ | Editing a knowledge-base fragment |
./tools/capture-thumbs.sh | assets/img/thumbs/ | Changing a page's masthead |
./tools/build-all.sh | Runs everything below, in order | Any edit, before pushing |
./tools/build-pdf.py | assets/pdf/ | Editing a page that has a downloadable PDF |
./tools/version-assets.py | Stamped links in every page | Editing any CSS or JS, and always last |
node tests/run-all.mjs | Pass or fail | Touching anything under functions/ |
Cache stamping, and why order matters
Browsers hold on to CSS and JS. Edit a stylesheet, reload, and you can still be looking at the old one. version-assets.py fixes that by appending a short hash of each file's contents to its link, so style.css?v=427c1711 becomes a different URL the moment the file changes and the browser fetches it again on its own.
build-pdf.py exists because printing hands the finished document to a browser you do not control. On 26 August 2026 the same page printed onto one sheet in Chrome and two in WebKit, because the two engines disagree about CSS multicolumn inside printed pages. Rendering the PDF here, from the same page and the same print stylesheet, means every visitor downloads an identical file. Run --check to see whether any PDF is older than the page it came from.
It has to run last. The knowledge-base pages, sskb.html and sitemap.html are all generated, and each generator writes plain unstamped links. Stamping before them means stamping pages that are about to be overwritten. The order is: the knowledge-base builds, then the SSKB build, then the sitemap, then version-assets.py.
Running it twice in a row does nothing the second time, so when in doubt, run it again.
Why generate rather than serve dynamically
The old sitemap.php scanned the directory on every request. That is elegant until the host stops running PHP, at which point it serves its own source code instead. A generated file has none of that fragility: it is just HTML, works anywhere, and costs nothing per request.
The same reasoning drives the thumbnails. Rather than a live screenshot service, headless Chrome captures each page's masthead once and writes a JPEG. Swapping in hand-made artwork means dropping a file with the same name into the folder; the markup never changes.
Tests
The suite runs in plain Node with no dependencies, stubbing the outbound fetch so nothing is ever really sent. It covers validation, honeypot behavior, HTML escaping, provider failures, Turnstile verification failing closed, and routing.
It exists because a live 500 is an expensive way to discover a bug that a test catches instantly. That is not hypothetical either: the contact form shipped broken twice before the suite existed.
Run the tests before pushing anything under functions/. They take about a second and have caught real regressions, including stale assertions after an intentional behavior change, which is exactly what you want them to notice.
Previewing locally
Pages use relative paths, so opening index.html straight from disk renders correctly. The one exception is the drawer menu, which fetches its own markup, and browsers block fetch on file:// regardless. For the full thing including navigation:
python3 -m http.server 8000
Then visit http://localhost:8000. API routes need npx wrangler dev instead, since those require the Worker runtime rather than a static file server.