Skip to content

ADR 0001: Static documentation site publishing architecture

  • Status: Accepted
  • Date: 2026-08-30
  • 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: MkDocs with the Material theme (mkdocs-material).
  2. Python-based build tooling integrates cleanly with existing repository scripts.
  3. Built-in client-side WebWorker search indexes markdown files without requiring third-party search backends.

  4. Native support for syntax highlighting, code copy buttons, tabbed content blocks, and collapsible navigation sections.

  5. Hosting Platform: Cloudflare Pages.

  6. Provides low-latency global CDN edge delivery with TLS certificate provisioning.

  7. Direct file upload support via Cloudflare Wrangler CLI.

  8. CI/CD Pipeline: Forgejo Actions.

  9. A workflow in .forgejo/workflows/publish.yaml runs on every push to the master branch.

  10. The workflow installs Python dependencies, compiles the static HTML artifact to site/, and deploys to Cloudflare Pages via npx wrangler pages deploy.

  11. Landing Page Strategy:

  12. 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.

Negative

  • Cloudflare API tokens (CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID) must be stored as Forgejo repository secrets.
  • Build runners require Python and Node.js execution environments.