ADR-0004: MkDocs Material for Documentation Platform¶

Status: Accepted Date: 2024-12-01 (Estimated) Deciders: GetCimple Team Tags: documentation, tools, developer-experience

Context¶

GetCimple needs comprehensive documentation for two audiences: - Internal: Business processes, architecture, planning, feature specs - Customer: Public-facing help docs, API documentation

Requirements: - Static site generator for fast, secure documentation - Support for dual sites (internal + customer) from single repo - Markdown-based for easy editing with AI tools (Claude Code) - Good search functionality - Professional appearance for customer-facing docs - Protection for internal docs (behind Cloudflare Access) - Version control integration (Git) - Cloudflare Pages deployment

Constraints: - Must be simple enough for 3-person team to maintain - Python-based tooling acceptable (team familiar) - Budget: Free or minimal cost - Must support extensive frontmatter and navigation customization

Options Considered¶

Option A: MkDocs Material¶

Description: Python static site generator with Material Design theme, extensive plugin ecosystem.

Pros: - ✅ Markdown-based: Simple, Git-friendly, AI-tool compatible - ✅ Material theme: Professional, modern, customizable - ✅ Dual sites: Easy to configure multiple MkDocs instances - ✅ Excellent search: Built-in search with advanced features - ✅ Navigation: Flexible nav with auto-sidebar, tabs, sections - ✅ Frontmatter: Rich metadata support via plugins - ✅ Plugin ecosystem: Mermaid diagrams, admonitions, snippets - ✅ Free: Open source, no licensing costs - ✅ Cloudflare Pages: First-class deployment support - ✅ Python ecosystem: Fits with team skills

Cons: - ❌ Python dependency (requires .venv management) - ❌ Build time increases with large sites - ❌ Limited interactive components (static site) - ❌ Some plugins require configuration tweaking

Estimated Effort: 1-2 days initial setup, minimal ongoing maintenance

Option B: Docusaurus¶

Description: React-based documentation framework by Meta.

Pros: - ✅ React-based (matches frontend stack) - ✅ MDX support (interactive components) - ✅ Versioning built-in - ✅ Good documentation and community

Cons: - ❌ Node.js-based (adds to monorepo complexity) - ❌ More complex than MkDocs (steeper learning curve) - ❌ Heavier builds (React bundle size) - ❌ Dual sites require separate repos or complex config - ❌ Overkill for static documentation needs

Estimated Effort: 2-3 days setup

Option C: VitePress¶

Description: Vue-based static site generator, fast builds.

Pros: - ✅ Very fast builds (Vite-powered) - ✅ Simple Markdown-based - ✅ Modern, clean design

Cons: - ❌ Vue-based (doesn't match React frontend stack) - ❌ Less mature than MkDocs or Docusaurus - ❌ Smaller plugin ecosystem - ❌ Dual-site configuration less documented

Estimated Effort: 2-3 days setup

Decision¶

We chose: Option A - MkDocs Material

Rationale: 1. Simplicity: Markdown + Python is simple, no JavaScript build complexity 2. Dual sites: Easy to configure internal + customer docs with separate configs 3. Professional appearance: Material theme looks polished for customer-facing docs 4. Search quality: Built-in search excellent for navigating extensive internal docs 5. AI tool compatibility: Plain Markdown works seamlessly with Claude Code, no MDX/JSX complexity 6. Proven: Widely used for technical documentation (Python, Kubernetes, etc.) 7. Plugin ecosystem: Extensions for diagrams, admonitions, code blocks cover all needs

Key Trade-offs Accepted: - We're accepting Python dependency (requires .venv) for simplicity elsewhere - We're accepting static-only sites (no interactive components) because documentation doesn't need interactivity - We're deferring versioning features to post-MVP (not needed yet)

Consequences¶

Positive¶

✅ Fast authoring: Write in Markdown, see changes instantly with hot reload
✅ AI-friendly: Claude Code can edit documentation easily (no build step confusion)
✅ Dual deployment: Internal + customer docs on separate domains with single workflow
✅ Professional: Material theme provides polished customer-facing docs
✅ Search: Users can find information quickly in extensive docs
✅ Cloudflare integration: Deploy via GitHub Actions, automatic SSL, global CDN
✅ Version control: Full Git history for documentation changes

Negative¶

⚠️ Python dependency: Team must maintain .venv, pip requirements.txt
⚠️ Build time: Large sites (100+ pages) can take 30-60 seconds to build
⚠️ Static only: Cannot add interactive calculators or tools within docs
⚠️ Navigation configuration: .pages files and frontmatter can be finicky

Risks¶

Risk	Likelihood	Impact	Mitigation
MkDocs build becomes slow (>2 minutes)	MEDIUM	LOW	Optimize build via caching; split into smaller sites; acceptable for docs
Python version conflicts	LOW	LOW	Lock Python version in .venv; document setup in README
Material theme breaking changes	LOW	MEDIUM	Pin Material version; test upgrades in staging; acceptable lag on updates

Compliance Note¶

ACSC Essential 8 Impact: - Not directly applicable: Documentation platform is internal tooling

Australian Data Residency: - Static sites: Served globally via Cloudflare CDN (no sensitive data in docs) - Internal docs: Protected via Cloudflare Access (email authentication) - Source control: GitHub (US company) acceptable for documentation source

Audit Trail: - All documentation changes tracked via Git commit history - Internal docs deployment protected (only team members can access)

Implementation Notes¶

Prerequisites: - Python 3.11+ installed - pip and venv available - GitHub repository configured

Integration Points: - GitHub Actions: Automated builds on push to main - Cloudflare Pages: Deployed to getcimple.com/docs (customer) and internal.docs.getcimple.io (internal) - Cloudflare Access: Zero Trust authentication for internal docs - Git: Markdown files version controlled

Monitoring: - Cloudflare Analytics for docs traffic - GitHub Actions logs for build status - No application monitoring needed (static sites)

Documentation Updates Needed: - ✅ MkDocs setup in README.md - ✅ Contribution guidelines for documentation - ✅ Internal docs guide in docs-internal/CLAUDE.md

Revisit¶

Revisit By: 2026-01-01 or when documentation exceeds 500 pages Blast Radius: MEDIUM - Affects documentation platform, team editing workflow

Conditions for Revisit: - Build times exceed 3 minutes consistently - Need for interactive components (calculators, configurators) - Team wants single documentation stack (React-based like Docusaurus) - MkDocs Material theme no longer maintained

Next Review: 2025-07-01 (evaluate build performance and team satisfaction)

References¶

Version History¶

Version	Date	Author	Changes
1.0	2025-10-20	Claude	Initial ADR capturing historical decision