Skip to content

ADR 0007: Docs as code with MkDocs

  • Status: Accepted
  • Date: 2026-09-11

Context

Knowledge lived in chat transcripts, memory files and heads. Diagrams in design tools go stale because they are not reviewed with the code that invalidates them.

Decision

This repository: MkDocs Material, Markdown, Mermaid diagrams as code, ADRs, flows and runbooks, auto-published to GitHub Pages at solidus-docs.keferboeck.com on every push to main. Database ER diagrams and flowcharts are always Mermaid, never Figma; wireframes stay in Figma and are linked. Updating the docs is part of the definition of done via the PR template.

Consequences

Docs are reviewed like code and are always at the latest version. The site is private-repo sourced but publicly served; nothing secret may ever be written here (secrets stay in .kamal/ files and password managers).