A docs site for a framework should answer the implicit question every visitor brings: "OK, but is this thing real? Could I actually build something with it?". The most honest answer is to be one yourself.
This site is a tinkerdown app — markdown files, one configuration file, no React. Every page you see is rendered by tinkerdown, which runs on top of LiveTemplate. The bug-finding loop is a feedback cycle: building the docs uncovers latent issues in the framework, and we fix them in the framework rather than working around them in the site.
Concrete examples this site found and the framework absorbed:
ws:// for HTTPS pages (G11) — every interactive block silently failed under HTTPS. The site was the first HTTPS-served tinkerdown deployment with lvt-source blocks; the bug had no other discovery path.compressionMiddleware's deferred gz.Close() flushed a 23-byte trailing gzip frame that Chrome rejected as ERR_CONTENT_DECODING_FAILED. Caught when the patterns reverse-proxy started erroring.None of these would have surfaced in unit tests. They needed a real, reasonably-trafficked site running with real assets.
The catalog this site exposes is itself driven by the same lvt-source="patterns" REST binding the site uses everywhere:
That number isn't hardcoded. It's a server-side template render, executed when this page loaded, against a live JSON endpoint of a separate fly.io deployment.
A few site-specific moving parts live in the livetemplate/docs repo, not in tinkerdown itself:
| Piece | Lives in | Why not in tinkerdown |
|---|---|---|
| Source-of-truth matrix (which repo owns which doc) | content/_meta/source-of-truth.{md,yaml} |
Specific to this docs site's content layout |
| Sync program (cross-repo content mirror) | cmd/sync/ (Go) |
Specific to this site's release-tag-driven sync model |
| GitHub Actions sync workflow | .github/workflows/sync.yml |
Per-deployment ops choice |
| Recipes content (this page included) | content/recipes/ |
Just markdown |
Everything else — proxy routing, theme tokens, mermaid bundling, lvt-source REST, wss:// scheme detection, edit-on-GitHub links — lives in tinkerdown as generic features. The discipline is: if the site needs it, tinkerdown should provide it for any site.
patterns source, different view