Skip to main content

ADR 0018 — Documentation Site (Docusaurus)

Status: Accepted (Phase 12) Context date: 2026-07

Context​

The platform has accumulated 12 architecture docs, 8 ADRs, 7 OpenAPI specifications, 5 event schemas, a WebSocket protocol spec, and SDKs for JavaScript/Swift/Android — all as raw markdown and YAML/JSON scattered across the repository. There is no unified, browsable documentation site. Developers must navigate raw files in the repo to find information.

Key requirements:

  • Browsable — searchable, organized, with sidebar navigation.
  • Interactive API reference — auto-generated from OpenAPI specs with "try it" panels.
  • Diagram support — Mermaid diagrams already in architecture docs must render.
  • Low maintenance — docs should sync from the source of truth in docs/ and contracts/.
  • CI-friendly — npm run build must succeed without broken links.

Decision​

Create a self-contained Docusaurus 3.x site at docs-site/ with:

  1. docusaurus-plugin-openapi-docs (PaloAltoNetworks, v4.x) for interactive API reference from all 7 OpenAPI specs.
  2. @docusaurus/theme-mermaid for rendering Mermaid diagrams.
  3. Copy, not symlink — a scripts/sync-docs.sh script copies architecture docs and ADRs from docs/ into the Docusaurus tree with frontmatter injection. Symlinks were rejected because they break on some CI runners and Windows.
  4. No versioning initially — the API is pre-1.0; versioning adds complexity without benefit yet.
  5. Six sidebar categories: Getting Started, Architecture, API Reference, SDKs, Events & Protocols, ADRs.

Alternatives Considered​

OptionRejected Because
MkDocs + MaterialNo native OpenAPI rendering; separate plugin ecosystem.
Nextra (Next.js)Heavier runtime; less mature plugin ecosystem for OpenAPI.
RedoclyExcellent for API-only docs but weak for narrative documentation.
GitHub WikiNo CI integration, no sidebar control, no OpenAPI rendering.

Consequences​

  • Positive: Unified documentation site with interactive API reference, Mermaid diagrams, and organized navigation. Build-time link validation catches stale references.
  • Positive: docs/ remains the source of truth. The sync script is idempotent and runs before every build.
  • Negative: Duplicated content between docs/ and docs-site/docs/. The sync script mitigates this but adds a build step.
  • Negative: OpenAPI docs are generated and .gitignored, requiring npm run gen-api-docs before build.
  • Follow-up: Add doc versioning when the API reaches 1.0. Consider Algolia DocSearch for full-text search.