Appearance
ADR 0001: Static documentation site publishing architecture
- Status: Accepted (updated 2026-11-08)
- Date: 2026-08-30 (updated 2026-11-08)
- Context: The repository serves as a Git DevOps reference guide. Reading markdown files directly inside git repositories introduces friction for search, navigation, mobile reading, and quick operational lookup. A compiled static documentation website provides instant text search, categorized sidebar navigation, copyable code snippets, and high-performance global hosting.
Decision
We will publish the repository markdown files as a static documentation website using the following components:
Static Site Generator: VitePress.
- Successor to VuePress; Node.js-native build tooling that integrates with the existing Node.js runtime on runners.
- Built-in full-text search via WebWorker index (no third-party search backend required).
- Native syntax highlighting, code copy buttons, dark/light mode, and collapsible sidebar navigation.
- Replaces MkDocs (deprecated upstream, Python dependency chain adds build complexity).
Hosting Platform: Cloudflare Pages.
- Provides low-latency global CDN edge delivery with TLS certificate provisioning.
- Direct file upload support via Cloudflare Wrangler CLI.
CI/CD Pipeline: Forgejo Actions.
- A workflow in
.forgejo/workflows/publish.yamlruns on every push to themasterbranch. - The workflow installs Node.js dependencies, compiles the static HTML artifact to
site/, and deploys to Cloudflare Pages vianpx wrangler pages deploy.
- A workflow in
Landing Page Strategy:
- The repository root
README.mdis mirrored intodocs/index.mdduring builds to maintain a single source of truth for both repository browsing and static site landing.
- The repository root
Consequences
Positive
- Developers and DevOps engineers get instant fuzzy search across all Git guides, recipes, and recovery runbooks.
- Zero server infrastructure maintenance on self-hosted machines.
- Clean separation between documentation authoring in markdown and production static asset generation.
- VitePress is actively maintained (MkDocs is deprecated); faster build times due to Vite-based HMR and bundling.
Negative
- Cloudflare API tokens (
CLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_ID) must be stored as Forgejo repository secrets. - Build runners require Node.js execution environment (already satisfied by existing
noderunner tag). - Angle brackets in inline code (e.g.
<sha>,<branch>) must be escaped or handled viamarkdown.html: falseto prevent Vue template compiler errors. This is configured globally indocs/.vitepress/config.mjs.
Migration Notes
- MkDocs
mkdocs.ymlhas been replaced withdocs/.vitepress/config.mjs. The sidebar navigation was programmatically converted from the MkDocs nav structure. - The
scripts/build-docs.shhelper was updated to usenpx vitepress build docsinstead ofmkdocs build. - The
.venv-buildvirtual environment andmkdocs.ymlwere removed. - All cross-references to scripts (e.g.
../../scripts/foo.sh) were updated to point to the Forgejo repository URL since VitePress treats relative paths outsidedocs/as dead links.