ADR-0003: Docs-as-Code with MkDocs Material¶

Context¶

The team was using Google Docs for engineering documentation. Problems:

• Docs are disconnected from code — no way to see which doc relates to which file
• No version control — docs can't be reviewed in PRs alongside the code they document
• No search across the engineering knowledge base
• New engineers must be told where to find docs (usually a Slack message or tribal knowledge)
• GitHub Wikis require a paid GitHub plan or a public repo — neither is available

Decision¶

Adopt docs-as-code using MkDocs Material, with:

• All docs as .md files in docs/ directory, versioned in the same repo as the code
• GitHub Actions CI builds the site on every push/PR to main
• Cloudflare Pages hosts the rendered site (free, no limits, global CDN)
• GitHub Discussions for async Q&A, ADRs under discussion, and incident retrospectives

Rationale¶

Consequences¶

Becomes easier: - Docs are reviewed in the same PR as the code they describe — drift is caught at review time - Search is instant and client-side — no server needed - New engineers find docs by opening the repo, not by asking in Slack - Mermaid diagrams are rendered automatically — no separate diagramming tool - Cloudflare Pages provides PR preview URLs — reviewers can see rendered docs before merge

Becomes harder: - Team must write docs in Markdown (small learning curve) - mkdocs.yml nav section must be updated when new pages are added - Cloudflare account and API token must be set up once (documented in .github/workflows/docs.yml)

Setup required (one-time)¶

1. Create a free Cloudflare account
2. Create a Pages project named flexli-dms-docs (Direct Upload)
3. Add CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID to GitHub repo secrets
4. Optional: set docs.flexli.in as a custom domain in Cloudflare Pages settings

After this one-time setup, every push to main that changes docs/ or mkdocs.yml will automatically build and deploy the site.