Skip to content

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:

  1. 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).
  2. Hosting Platform: Cloudflare Pages.

    • Provides low-latency global CDN edge delivery with TLS certificate provisioning.
    • Direct file upload support via Cloudflare Wrangler CLI.
  3. CI/CD Pipeline: Forgejo Actions.

    • A workflow in .forgejo/workflows/publish.yaml runs on every push to the master branch.
    • The workflow installs Node.js dependencies, compiles the static HTML artifact to site/, and deploys to Cloudflare Pages via npx wrangler pages deploy.
  4. Landing Page Strategy:

    • The repository root README.md is mirrored into docs/index.md during builds to maintain a single source of truth for both repository browsing and static site landing.

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_TOKEN and CLOUDFLARE_ACCOUNT_ID) must be stored as Forgejo repository secrets.
  • Build runners require Node.js execution environment (already satisfied by existing node runner tag).
  • Angle brackets in inline code (e.g. <sha>, <branch>) must be escaped or handled via markdown.html: false to prevent Vue template compiler errors. This is configured globally in docs/.vitepress/config.mjs.

Migration Notes ​

  • MkDocs mkdocs.yml has been replaced with docs/.vitepress/config.mjs. The sidebar navigation was programmatically converted from the MkDocs nav structure.
  • The scripts/build-docs.sh helper was updated to use npx vitepress build docs instead of mkdocs build.
  • The .venv-build virtual environment and mkdocs.yml were 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 outside docs/ as dead links.

Git Master — Git Reference for Every Skill Level