ADR-005: Docusaurus for Internal and External Documentation
| Attribute | Value |
|---|
| Status | Accepted |
| Date | March 2026 |
Decision
Use Docusaurus with one codebase and two deployments: public docs at docs.checkyourcloud.com (Vercel) and internal docs at internal.checkyourcloud.com (Cloudflare Pages + Cloudflare Access).
Rationale
- Markdown-native: All documentation lives in Git — versioned, diffable, reviewable via PR
- Mermaid support: Architecture diagrams embedded directly in
.md files, version-controlled alongside content
- Zero infrastructure overhead: Static site generation means no VMs, no servers, no databases
- One codebase: Shared content (security, privacy, API reference) lives in
docs/ and is included in both builds. Internal-only content in docs-internal/, external-only in docs-external/
- Access control without VMs: Cloudflare Access handles authentication for internal docs via Google/GitHub OAuth — free for up to 50 users
Hosting
| Deployment | Platform | Auth | Cost |
|---|
docs.checkyourcloud.com | Vercel (free tier) | None — public | $0 |
internal.checkyourcloud.com | Cloudflare Pages + Access | Google/GitHub OAuth | $0 up to 50 users |