The day the reader stopped being ours
build-kb.py had this site's folders written into it in four places, so it could only ever build one knowledge base. Fixing that, and adding Markdown, is what turned it into something sellable.
What we were doing. Building a demonstration knowledge base for a company that does not exist, so that prospective clients could see the reader holding real content instead of imagining it.
It surfaced something more useful than the demo. build-kb.py had kb/ written into it in four places: the source folder, the output folder, and two link builders. It could only ever build this site's knowledge base. You could not have sold the engine without fixing that, and nobody had noticed, because until that morning there had only ever been one instance.
What changed
The script now takes --source, --out and --base, and defaults to this site's own paths so running it bare behaves exactly as it always did.
It also reads Markdown. A fragment can be .md with front matter or .html with the old metadata comment, and both work. Markdown is the format to prefer now, for the obvious reason: nobody is going to hand a café owner an HTML file to edit. The converter is written by hand rather than pulled from a library, because this site has no dependencies and is not going to grow a build step to gain one. It covers headings, paragraphs, bulleted and numbered lists, bold, italic, inline code, links, fenced code blocks, pipe tables, and raw HTML passed straight through for anything it does not model.
The bug worth remembering
Parameterizing the paths silently broke every relative link in the new instance. The generated pages came out with hrefs like:
../../content/demo/acme/about.html
From content/demo/acme/operations/, ../../ lands in content/demo/, so that resolves to content/demo/content/demo/acme/about.html, which does not exist.
The cause: the depth values passed around inside the builder describe where a page sits inside its instance, 1 for About and 2 for a collection page. How far that is from the site root also depends on where the instance itself sits. For kb/ those are the same number. For content/demo/acme/ they differ by two.
Fixed inside rel(), so every caller benefits at once:
depth += BASE.count("/") - 1
Nothing errored. The build reported success and wrote twenty pages, every one of them with broken navigation.
The technique that caught it
Two checks, both worth reusing whenever a generator is refactored.
Rebuild the old thing and diff it. The existing knowledge base was rebuilt with the new parameterized script and compared against the previous output. Byte for byte identical apart from the timestamp. That is what proves a refactor changed nothing it should not have.
Resolve the generated links against the filesystem. A short script walked the output, took every relative href, resolved it from the page's own directory, and checked the file existed. That is what found the broken paths, and it found them in seconds.
Neither check is clever. Both were faster than reading the code and hoping.
What it means
There are three instances of the same reader running now: this site's knowledge base, Storytelling Technique, and the Acme demonstration. One engine, three bodies of content, three skins. That is the thing being offered on the Tools You Can Own page, and it only became true once the folder names came out of the script.