ADR-0032: Documentation site
- Status: Accepted
- Date: 2026-10-12
- Builds on: ADR-0007, whose pinning rules the
site's workflow follows, and ADR-0030, which makes
mainthe latest release.
Context
The guides in docs/ were readable only on GitHub, one file at a time, with no search,
no landing page, and nothing in Vietnamese although the interface is bilingual. The
Quickstart lived in the README, so the guides had no first page to start a reader on.
The guides are also the reference contributors keep aligned with the code in the same pull request. A site that copied them, or asked for front matter or MDX the GitHub view does not need, would give every change a second place to forget.
Decision
- Docusaurus 3, in
website/, readingdocs/in place. The pages are the guides as they are, parsed as CommonMark;website/holds only the site around them: its configuration, sidebar, landing page, and translations. It has its ownpackage.jsonand lockfile, so the application's build, browser tests, and dependency audit never load it. Docusaurus has versions and languages built in, and the repository already builds with Node.js. MkDocs Material, now in maintenance, would add a Python toolchain; Starlight versions documentation only through a third-party plugin. - A broken link fails the build. Links, anchors, and Markdown file links all throw.
A link to a file beside
docs/, such asCONTRIBUTING.md, still works on GitHub and is pointed at that file onmainin the site, where it would otherwise name nothing. - Published from
mainonly, to GitHub Pages, by a workflow.mainis the latest release, so the site describes what can be installed;developis only built, on every pull request, to keep links whole. The deploy job alone holdspages: writeandid-token: write, and thegithub-pagesenvironment accepts onlymain. Every action is pinned to a commit SHA. There is one version of the documentation until a release breaks what an earlier one documented. - English is the source; Vietnamese is a translation of it. The English guides stay in
docs/. Each translation sits underwebsite/i18n/vi/at the same path, and a page with none falls back to its English one. The guides, the Getting started page, the REST API prose, and Configuration are translated; the architecture, the implementation status, and these decision records stay in English, as engineering records whose translation would drift from what they record. Product terms stay in English in both, as the glossary inCONTRIBUTING.mdalready says for the interface. - Search runs in the browser. A local index in both languages needs no account or third party; a hosted search can replace it when the site has the readers to need one.
- The site's dependencies are audited like the application's, at high severity, with
one difference: an advisory no release fixes yet may be listed in
scripts/ci/audit-website.shwith the reason it cannot reach a static site, and the check fails once npm stops reporting it. Fixable transitive advisories are pinned to a fixed version with npmoverrides.
Consequences
- A guide is written once, for GitHub and the site together. A new guide is placed in
website/sidebars.json purpose; the decision records are listed by number. - A change to a guide that has a Vietnamese translation updates the translation in the same pull request, or the two disagree on the site.
- Documentation fixes reach the site with the next release, not when they merge into
develop. A fix that cannot wait is a hotfix. - The site carries a JavaScript dependency tree of its own, which Dependabot updates weekly. An override is removed once Docusaurus requires a fixed version itself.
- GitHub Pages must be switched to deploy from GitHub Actions once, by hand, before the first deployment.
Note, 2026-11-18: scripts/ci/audit-website.sh is now scripts/ci/audit-npm.sh, which takes the package directory and audits the application's own npm dependencies by the same rule.