1. Use Docusaurus for internal documentation
Date: 2026-05-03
Status
Accepted
Context
We need an internal documentation hub for ADRs, architecture notes, and runbooks. The solution should scale as a static site on a CDN and stay easy for engineers to contribute (Markdown in Git).
Decision
Use Docusaurus 3 for the documentation site, with Bun as the package manager and Cloudflare Access (or equivalent) in front of the deployed static output for GitHub-organization-scoped access.
Consequences
- Positive: Strong docs UX (sidebar, search plugins, MDX), static output, large ecosystem.
- Positive: Auth stays at the edge; no session logic required in the doc generator.
- Tradeoff: In-app OAuth is not part of the doc site; multi-app SSO patterns will be handled in other apps or shared packages when added.