Why this pattern
The problem it solves
A conventional documentation site leans on a generator (MkDocs, Docusaurus, Hugo) plus a plugin ecosystem. That buys you a lot, but it also means a toolchain to install, a config to learn, a build step to run, and a dependency tree that drifts and breaks between machines and over time. For a personal, long-lived knowledge base you curate — where you shape the structure, Claude writes the pages, and you read the result — that overhead earns little and costs upkeep.
This scaffold takes the opposite bet: the rendered HTML is the source, and the only tooling is a few hundred lines of Python standard library.
What this scaffold does instead
| Concern | How it's handled |
|---|---|
| Navigation | _lib/_nav.py scans docs/pages/. Each directory is a tab; each .html file is a page. No central nav list. |
| Page chrome | _lib/_layout.py renders one shared shell; _lib/_wrap_handwritten.py bakes it onto every authored <main>. Change the layout once, re-wrap, done. |
| Per-tab tweaks | An optional _tab.json per tab overrides label, ordering, and sidebar grouping — local to that tab, no global config. |
| Live preview | _lib/_serve.py: stdlib HTTP + mtime polling + Server-Sent Events. No watchdog, no websocket library. |
| Dependencies | None. python3 is the whole requirement. |
Result: adding content is a one-step action — create an HTML file, run the wrap script, commit.
The tradeoffs — honest version
- You write HTML, not Markdown. No Markdown-to-HTML convenience, no fenced-code niceties out of the box. For an LLM author this is a non-issue — Claude emits HTML as readily as Markdown — but a human typing pages by hand will feel it.
- No plugin ecosystem. Search, diagrams, math, versioning — anything a mature generator ships as a plugin, you'd add yourself. The header has a placeholder search button that's intentionally a stub.
- The wrap step is manual. Chrome isn't regenerated on save; you run
_wrap_handwritten.pyafter structural changes. The dev server reloads content live, but new pages/tabs need a wrap to get their chrome. - You own the CSS. Theming is a single
assets/style.cssyou edit directly, not a configured theme. More control, more rope.
When this pattern shines
- Knowledge bases you curate — you shape the structure; Claude writes the HTML directly into
pages/; you read the result. - Long-lived personal sites where "still builds in three years with zero dependency rot" matters more than a rich plugin set.
- Air-gapped or minimal environments — if it has Python, it runs.
When it doesn't
- Human-authored docs where Markdown ergonomics and a copy-button-on-code-blocks experience matter — reach for MkDocs Material.
- You need full-text search, i18n, or versioned docs today — those come free in mature generators and would be real work here.
- A large team that wants a single auditable nav file and a CI-enforced build contract.