Skip to content

ADR-002: Build the guidance/documentation site with MkDocs Material on Azure Static Web Apps

Status

Accepted — 2026-06-06 (ratified by Nikola Jeremić: "it will be 4, we only have markdown files")

Context

The development guidance package is a folder of plain markdown files in the ExpertGroup.Documentation.Guidance repo, consumed three ways: by developers reading the repo, by Claude sessions via CLAUDE.md references, and — needed now — by everyone through a centralized website. The site generator must build from the markdown as-is, so the repo remains the single source of truth and no content is forked into a CMS or framework. Candidates considered: MkDocs Material, Docusaurus (React/MDX — drags a JS framework into a content repo; team is Angular-heavy), Astro Starlight (younger, another toolchain), Azure DevOps wiki (kept as a free secondary view, but per-project and not a branded central URL).

Decision

We will build the documentation site with MkDocs + Material theme, themed to the Expert Group brand book (Fiord/Mirage/Waikawa palette, Amaranth accent, TT Firs Neue with Arial fallback), with built-in search and Mermaid rendering for C4 diagrams. It deploys to Azure Static Web Apps via the repo's Azure Pipeline (mkdocs build → AzureStaticWebApp@0, skip_app_build: true), mapped to the environment-branch model: production branch → live site, development → preview environment. Scope: documentation/handbook sites only — rulings for marketing sites, public custom-code sites, and internal apps (Webflow/Next.js/Angular split) remain unratified proposals, not covered by this ADR.

Consequences

Easier: zero content migration (markdown in, site out); one pip install build with no Node toolchain; search and diagrams work on a static host; the repo stays authoritative for humans, Claude, and the website simultaneously. Harder/accepted: Python enters an otherwise .NET/Node toolchain (build-only, CI-contained); deep visual customization is bounded by the Material theme; TT Firs Neue webfonts must be supplied from the existing font license before the site is fully on-brand (Arial fallback until then).