Skip to main content

ADR-0018 — Docusaurus 3.x for the engineering bible

  • Status: Accepted
  • Date: 2026-05-08
  • Decision-makers: Tom Anderson

Context​

The engineering bible needs:

  • Markdown/MDX-based content (everything reviewable in git)
  • Sidebar navigation across many docs
  • Mermaid diagram rendering (ADR-0017)
  • Full-text search
  • Custom branding (Kvick navy + orange)
  • Easy Cloudflare Pages deployment
  • A categories/section navigation pattern that scales to ~100 docs

Alternatives:

  • Docusaurus 3.x — Meta-maintained, React-based, mature plugin ecosystem, MDX-native, good for technical docs
  • MkDocs Material — Python-based, lighter, but less React/MDX integration
  • VitePress — Vue-based, lightweight, good for technical docs
  • Mintlify — hosted SaaS, beautiful but vendor lock-in and recurring cost
  • Static site generator + handrolled — too much work

Docusaurus is the boring choice here (boring tech) — long track record, vast plugin ecosystem, well-documented.

Decision​

Use Docusaurus 3.x. Specifically:

  • TypeScript template (npx create-docusaurus@latest docs-site classic --typescript)
  • @docusaurus/theme-mermaid for diagrams
  • @easyops-cn/docusaurus-search-local for offline-friendly search (no Algolia)
  • Custom CSS (src/css/custom.css) for Kvick branding (DM Serif Display headings, JetBrains Mono code, navy/orange palette)
  • routeBasePath: '/' — docs at the root, no blog
  • Deploy via Cloudflare Pages
  • static/CNAME set to bible.kvick.bike
  • Cloudflare Access gates the deployed bible site (auth required for Kvick employees + invited shop owners)

Consequences​

Positive:

  • Mature framework; problems have Stack Overflow answers
  • MDX lets us mix Mermaid + React components + Markdown freely
  • Cloudflare Pages's Docusaurus integration is one-click
  • Local search beats external Algolia for a private docs site (no external indexing)
  • Sidebar generation from filesystem structure is automatic

Negative:

  • A React-based framework runtime for a docs site — heavier than a true static site generator
  • Docusaurus version upgrades occasionally break theming
  • The build step takes ~30 seconds; not instant

Mitigations:

  • The built output is static HTML/CSS/JS; the runtime is what's heavy, not what's served
  • Pin to a Docusaurus minor version; upgrade deliberately
  • Build time is fine for a docs site that updates a few times a day

Notes​

The bible repo is separate from the Helm app repo. Deploy is automatic on push to main via Cloudflare Pages's GitHub integration.

See also​