Skip to content

ADR-0015: Internal documentation platform — ADO Wiki over MkDocs Material

Status

Accepted — 2026-04-03

Context

The Archon platform needs versioned internal documentation covering architecture, ADRs, runbooks, golden paths, best practices, and testing guides. The documentation must render Mermaid diagrams, be editable as markdown in git, and serve on the LAN without internet dependency.

MkDocs Material — what was tried

MkDocs Material was deployed from v0.1 through v0.6 as the documentation platform:

  • Serving stack: nginx container on caneast-c1-node2:[INTERNAL], serving pre-built static HTML from the gh-pages branch
  • Versioning: mike (Python tool) managed version snapshots (v0.1–v0.6) on gh-pages
  • Build pipeline: deploy.sh on caneast-c1-node2 ran mike deploy inside a Docker container (squidfunk/mkdocs-material:latest), then exported gh-pages to the nginx serve directory
  • Diagrams: Mermaid via pymdownx.superfences custom fences. D2 via Kroki was trialled (v0.5–v0.10) but rejected — required sidecar containers and a LAN build-time dependency (see ADR-0010)
  • Custom theming: deep purple/cyan dual palette with dark/light toggle, extra.css for diagram zoom overlay, diagram-zoom.js for click-to-zoom, mermaid-init.js for theme variables
  • Plugins: search, tags, glightbox (image zoom), mike (versioning)

Why MkDocs was removed

  1. Operational overhead: every doc change required a Docker-based mike build, gh-pages export, and nginx restart on caneast-c1-node2. A single-operator platform cannot justify a multi-step deploy pipeline for internal docs.
  2. Version sprawl: Kroki/D2 experiments created mike versions v0.5 through v0.10 with no meaningful content difference — just config iterations. Cleanup required manual mike delete for each.
  3. Build fragility: deploy.sh failed when the source repo had unstaged changes (common after manual mike operations). The git state on caneast-c1-node2 diverged from ADO repeatedly.
  4. Unnecessary infrastructure: nginx container, Docker image pulls, pip installs, mike, glightbox — all to serve markdown that ADO Wiki renders natively.
  5. Theme churn: custom CSS, JS, and colour schemes added complexity without improving documentation quality. Multiple PRs were spent adjusting theming instead of writing content.

Decision

Azure DevOps Wiki (code wiki) is the internal documentation platform for the Archon platform.

  • archon-docs repo published as a code wiki at dev.azure.com/caneast-platform/archon-platform/_wiki
  • Markdown rendered natively by ADO — no build step, no containers, no deploy script
  • Mermaid diagrams render natively in ADO Wiki fenced code blocks
  • All content remains in git — editable via ADO web UI or local clone
  • No custom CSS, JS, or theming — ADO Wiki provides consistent rendering

What was removed from archon-docs

  • docker-compose.yml (nginx serving)
  • deploy.sh (Docker-based mike build script)
  • mkdocs.yml (MkDocs Material configuration)
  • requirements.txt (pip dependencies)
  • docs/javascripts/diagram-zoom.js
  • docs/stylesheets/extra.css
  • site/ directory (build output, added to .gitignore)

What was retained

  • All markdown content — ADRs, _index.md, architecture docs, runbooks, golden paths, best practices, testing guides
  • docs/ directory structure unchanged
  • git history preserved

Public documentation — future state

Internal docs use real hostnames, IPs, and ports. Public-facing documentation on peries.ca will use the CanEast naming convention (see ADR-0008) with sanitized substitutions:

Internal Public
caneast-c1-node2, caneast-c1-node3 compute-node-01, compute-node-02
192.168.2.x 10.x.x.0/24 (network/mask only)
Real port numbers Functional descriptions
CAE prefix CanEast region prefix

Implementation plan (Phase 3+): - Pre-publish script in ADO CI/CD pipeline applies CanEast substitutions - Sanitized output deployed to peries.ca (Cloudflare, managed via Terraform) - Internal archon-docs repo remains the source of truth — public layer is a derivative

Alternatives considered

  • MkDocs Material (status quo): rejected — operational overhead documented above
  • GitHub Pages: rejected — platform uses Azure DevOps, not GitHub
  • Confluence: rejected — SaaS dependency, not self-hosted, not git-native
  • Docusaurus: rejected — same build/deploy overhead as MkDocs with a Node.js stack
  • Plain markdown in repo (no wiki): viable but loses navigation, search, and rendered Mermaid in the browser

Consequences

  • No build step for documentation — push to main, wiki updates automatically
  • Mermaid diagrams work natively — no plugins, containers, or custom JS
  • No versioned documentation snapshots (mike equivalent) — git history serves this purpose
  • No custom theming — accept ADO Wiki's default rendering
  • caneast-c1-node2 no longer serves archon-docs — nginx container and Kroki sidecar removed from docker-compose
  • Public docs on peries.ca require a separate CI/CD sanitization pipeline (Phase 3+)