The stylesheet nobody could see

← Previous Next →
Build Log · 2026-08-26

The stylesheet nobody could see

Browser caching misled us four times in one day, and the script written to end it introduced three bugs of its own, all of them about the order things run in.

What happened. Four separate times in one working day, a change was made, the file on disk was correct, and the browser kept painting the old version. The worst stretch was a button that had been restyled and verified in the file for the better part of an hour while it still looked wrong on screen. Each time the answer was the same: the browser was serving a cached copy of the stylesheet, and only a forced reload would shift it.

That is not a bug in anything. It is browsers doing exactly what they are supposed to do. But it wastes real time, and worse, it makes you doubt a change that already worked.

The fix

tools/version-assets.py appends a short hash of each file's own contents to every local stylesheet and script link:

<link rel="stylesheet" href="/assets/css/style.css?v=427c1711">

Change the file and the hash changes, so the browser sees a URL it has never fetched and gets the new copy. Leave the file alone and the browser keeps its cached copy, which is the behavior you want. 63 pages carry stamps now.

It also fixed something quietly wasteful. drawer.js had been fetching drawer.html with Date.now() on the end, which meant re-downloading the drawer markup on every single page load, forever. It now uses the same content hash.

Three bugs, all about ordering

Writing the script was easy. Getting it correct took three attempts, and each failure was the same shape: something else changed underneath it.

One. The first version matched only the string literal inside fetch('/drawer.html?v=' + Date.now()), so it replaced the URL and left the concatenation dangling. The result was ?v=9f6ae5f1' + Date.now(), which is worse than what it replaced. Fix: match the whole argument expression, not just the part that looks like a filename.

Two. Running it twice gave different answers. Stamping drawer.js changes drawer.js, which changes its hash, which makes the 18 pages linking it stale the moment they were stamped. Fix: stamp drawer.js first, then walk the pages.

Three. The documented build order was wrong. It said to stamp before running build-sitemap.py, but that regenerates sitemap.html, which has stylesheet links of its own, so exactly one page was left unstamped every time.

The rule this leaves behind

Any tool that rewrites files has to run after every tool that generates them. On this site that means:

  1. ./tools/build-kb.py and any --source variants
  2. cd content/SSKB && python3 build.py
  3. ./tools/build-sitemap.py
  4. ./tools/version-assets.py, always last

The test that matters is not whether it works. It is whether running it twice changes anything the second time. It does not now, and that is the property to check after touching it.