ADR-0002: Adopt MkDocs (Material) for Appcircle Internal Documentation¶

Status: ✅ Accepted
Date: 2025-12-24
Owners: @osmank, @team/architecture

Context¶

Appcircle internal documentation was previously published using mdBook (Markdown → static HTML). As the internal portal has grown (onboarding/offboarding, DevOps runbooks, architecture notes, operational guides), we need a documentation platform that behaves more like a “documentation portal” than a linear book.

Requirements / Constraints¶

We need:

Strong header menu and navigation UX
Clear information architecture, section-level top navigation, deep sidebar navigation, good ToC experience.
Light/Dark theme support
User-friendly toggle or auto mode preferred.
Markdown-first authoring
Source-of-truth must be Markdown in Git.
Minimal HTML/JS/CSS usage
Prefer configuration + Markdown extensions over custom front-end code.
SSO-protected internal access
Site must be accessible only via SSO (hosting/edge integration is acceptable).
Advanced search
Fast, accurate, highlighted results; suggestions are a plus.
Future portability
If we later move to another platform, Markdown content should remain reusable with minimal rewrite.

Decision¶

We will adopt MkDocs with the Material for MkDocs theme as the standard generator for the Appcircle internal documentation portal.

Key points:

Documentation remains Markdown-first in Git.
Navigation and header menus will be managed via mkdocs.yml (not custom HTML templates).
Search will use the built-in search plugin (client-side), with Material’s UX enhancements where needed.
Access will be restricted via SSO at the hosting/edge layer (e.g., Cloudflare Access, Google IAP, Azure App Proxy, oauth2-proxy), rather than building authentication into the static site generator.

Options Considered¶

Option A — Continue with mdBook¶

Pros - Markdown-first, simple and fast to build. - “Book” style works well for linear reading and tutorials. - Theme can be customized by overriding theme assets.

Cons - Navigation and portal-style header menus are more limited than portal-focused doc tools. - Advanced navigation patterns (tabs/sections) and portal UX usually require more theming work (CSS/JS). - Ecosystem for documentation-portal features is smaller.

Option B — MkDocs + Material (Chosen)¶

Pros - Strong documentation-portal UX: navigation, sections, ToC, and theme features are highly mature. - Built-in search plugin + Material UX options (highlight/suggest/instant) without external services. - Light/Dark/Auto theme patterns supported via configuration. - Markdown-first; rich extension ecosystem (admonitions, code fences, Mermaid, etc.). - Static output: easy hosting and easy to protect via SSO at the edge.

Cons - Requires Python toolchain and dependency management. - Some extensions/shortcodes may be MkDocs-specific; we must avoid overusing non-portable features. - SSO is not “built-in”; must be implemented by the hosting layer (which is acceptable for static sites).

Option C — Jekyll¶

Pros - Mature static-site generator; Markdown-based. - Commonly used with GitHub Pages and has broad community support.

Cons - Advanced docs UX (portal navigation, search, theme toggles) often needs extra Liquid templates and front-end work. - Search is not a first-class built-in docs feature; typically implemented with client-side JS (e.g., Lunr) and extra glue. - If hosted on GitHub Pages with built-in Jekyll build, plugin usage is restricted (safe mode / supported plugins list).

Option D — BookStack¶

Pros - Full-featured internal knowledge base (built-in search, permissions, SSO options). - Rich WYSIWYG editing and access control model inside the application.

Cons - Not a static site generator; requires running an app + database (operational overhead). - Content is not naturally “Markdown in Git” as the primary workflow. - Portability risk: migrating away later can be more expensive than static Markdown-based approaches. - Customization and workflow automation becomes more “app-centric” vs repo-centric.