ADR-0002 — Docs-as-code with MkDocs Material, served via existing nginx¶
Status: Accepted Date: 2026-05-11 Decision-maker: João Brazão
Context¶
A growing team needs documentation to onboard fast. The proposal that triggered this ADR recommended a stack of:
Auditing the actual VPS state revealed: - 32 containers already running - Forgejo is already deployed and serves as a software catalog - Most projects have no docs at all — the bottleneck is content, not tooling - RAM headroom exists (26 GB free), but Backstage's Node.js maintenance cost is significant - The team is still small — Backstage's discovery features have low marginal value
Decision¶
Replace the proposed Backstage-centric stack with a lighter, Forgejo-native stack:
Adopted:
- MkDocs Material as the rendering engine (Python, static output)
- Mermaid (built into MkDocs Material) for diagrams
- ADR Tools convention for decision records (shell-only, no infra)
- git-cliff for CHANGELOG auto-generation from conventional commits
- Custom document.infra-scanner skill in jb-skills-gateway for auto-updates
- Forgejo wikis for team-level free-form notes
- Nginx-served static site at docs.joaoluisbrazao.cloud
Rejected:
- Backstage OSS — premature for team size; Forgejo provides 70% of value with 5% of the maintenance cost
- TechDocs — disappears with Backstage
- Structurizr Lite — Mermaid C4 extension covers the need
- TypeDoc — no TypeScript projects of meaningful size; pdoc covers Python
Consequences¶
Positive
- Zero new containers for Phase 1 (MkDocs is a static-site generator)
- One Python container for Phase 2 (document.infra-scanner skill)
- Documentation lives in the same repos as the code — true docs-as-code
- New contributors edit Markdown in the editor they already use
Negative - No central software catalog UI like Backstage - Cross-project search not solved out of the box (deferred to MeiliSearch later if needed) - We will need to re-evaluate this ADR when the team exceeds 4 active engineers
Re-evaluation trigger: 4+ active engineers OR > 15 actively maintained projects.