0090. The docs site is generated from the repository by a small script, not built as a Duolith app
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: WP16 (docs site)
Context
The docs site has to show the guides (docs/guide/), the explanations and decision records, the language specification, the kit and glossary specifications, every diagnostic code, and the example apps. It needs search, headings that can be linked to, code blocks, tables, and the default theme in light and dark. duolith explain should be able to point at one page per code.
Building the site with Duolith itself (dogfooding) was the first choice. It does not fit yet. The language has no headings, code blocks, tables or plain anchors, because pages describe app screens and not documents. Every app is a single-page app whose shell and modules are addressed from /, so a built app cannot sit in a folder of another site. And the guides are markdown, which Duolith does not read. Turning around 180 markdown and YAML sources into .duo pages would mean adding document elements to the language only for this site.
Decision
The site is a static folder of HTML generated by tools/release/site/build.ts (pnpm docs:build, into docs/site/out/, which git ignores). Like the other scripts in tools/, it runs on Node with only its built-ins and the yaml parser.
- Sources. The markdown in
docs/guide/,docs/explanation/,docs/decisions/andspec/language/, plusspec/README.md,examples/README.md,examples/FEATURES.mdanddocs/site/home.md, goes through a small markdown renderer that handles the subset the repository uses. Raw HTML in the sources is shown as text. Only http, https, mailto and relative links become links; any other scheme (javascript:,data:, a protocol-relative//host) is shown as text, in markdown and in prose from the YAML specifications alike. A root-absolute link is read from the repository root, as GitHub reads it. Reference pages are generated fromspec/language/elements.yaml,spec/kit/*.yamlandspec/glossary.yaml, so nothing is typed twice. The plan indocs/plan/stays in the repository and is not on the site. - One page per code. Every E-code and W-code in
spec/diagnostics/catalogue.yamlhas a page aterrors/<CODE>.html. The page lists the pages that mention the code.duolith explainprints that page's address after the docs address, which is a placeholder until decision 0091 is settled. In prose, a code such as E0101 and a phrase such as "decision 0031" link to their pages. - Examples. Each folder in
examples/has a page with its line fromexamples/README.md, the rows ofFEATURES.mdthat show it, the commands that run it, and its source files. These pages link to the examples rather than embedding them, because a built app cannot run from a sub-folder (see Context). - Theme.
assets/site.cssstarts with the default theme's tokens fromspec/styling/default-theme.yaml. They are written as the same custom properties, with the same light and dark rules and the samedata-color-schemeswitch, as an app'stheme.css. The scheme button cycles through system, light and dark, and keeps the choice under the runtime's own storage key (decision 0043). - Search runs in the browser over an index that the build writes as a script (
assets/search-index.js), not as JSON, so search also works from afile://address. Every page is indexed whole, one entry per section (h2), so a result opens the section that matched. Queries read any script; pieces without a letter or digit are ignored. Enter opens the search page with every result, unless the arrow keys chose one. Every link on the site is relative. - Checks.
tools/release/site/check-links.ts(pnpm docs:links) fails on any relative link without a target, a#fragmentwith no matching id, a link to the repository on the web that names a missing path, a link with a scheme other than http, https or mailto, or a code without a page. CI builds the site and runs this check.
Alternatives considered
| Option | Why not |
|---|---|
| Build the site as a Duolith app | No document elements, apps are addressed from /, and no markdown input (see Context). Revisit once the language has a document profile or duolith build has a base path. |
| A static site generator (VitePress, Astro, Docusaurus) | Adds a large dependency tree and a second theme system to keep matching the default theme. The repository's markdown subset is small. |
| Embed every example, built, in an iframe | The build writes absolute /_duolith/ addresses, so it needs a base-path option in duolith build (Tooling) first. |
Consequences
- Docs are checked in CI: a broken link, a stale anchor or a code without a page fails the build.
- The markdown renderer handles only the subset in use. New syntax in a guide (footnotes, raw HTML) shows as text until the renderer learns it.
- To embed the live examples later,
duolith buildneeds a base-path option. Then the docs build can build each example intoexamples/<name>/live/. - The language server still links a code to the catalogue on GitHub (
explainLink). It should link to the docs page once the domain is chosen.