Skip to main content

ADR 0012: Documentation tooling

  • Status: accepted
  • Date: 2026-11-07
  • Decision makers: the user approved the plan; the tool choices were made by the orchestrating task

Context and problem statement​

The user asked for a technical architecture and API documentation website and for open-source tools picked for this product. The content must come from the real code and infrastructure, search must work offline, and nothing should send credentials from a docs page.

Decision drivers​

  • Generated API pages from many OpenAPI specs, one per service.
  • Architecture diagrams that cannot drift from one source.
  • No hosted services. No Algolia.
  • A section that can be left out of a public build by a single flag.

Considered options​

  • Docusaurus 3 with the OpenAPI plugin and theme.
  • Material for MkDocs. In maintenance mode since November 2025.
  • Zensical. Too new.
  • Starlight with starlight-openapi. The fallback if the OpenAPI plugin had not worked.
  • Scalar for the API reference. The alternative if the plugin had blocked.

Decision outcome​

  • Site: Docusaurus 3.10.2 with MDX, sidebars, built-in broken-link checks set to throw, and the official Mermaid theme.
  • API reference: docusaurus-plugin-openapi-docs and its theme 5.2.0, one spec per service, with the request panel switched off and no server URLs.
  • Specs: generated at build time from the Quarkus services by SmallRye OpenAPI through an opt-in Maven profile, not from production. Overlays add readable tags and the authentication schemes.
  • Lint: Spectral. It fails on invalid specs and reports other findings.
  • Architecture: the C4 model as code in Structurizr DSL, exported to Mermaid at build time. Mermaid sequence and state diagrams for flows.
  • Search: @easyops-cn/docusaurus-search-local, offline.
  • Quality: markdownlint and lychee for external links.
  • Decisions: MADR 4.0 records.

Consequences​

  • Good: one model feeds every C4 diagram; specs cannot drift from the code; the internal section is removed by one build flag.
  • Bad: the OpenAPI theme needs Docusaurus's faster build mode. With the default bundler it fails to compile.
  • Bad: summaries derive from Java method names until annotations are added to the services.
  • Bad: the Structurizr CLI needs JDK 21 and a download. The exported diagrams are committed so a normal build needs neither.

Confirmation​

npm run build and npm run build:public pass with broken links set to throw. scripts/check-public-build.sh proves the public build is free of internal text.

Sources​

docs-site/TOOLS.md, How these docs are built.