Skip to content

ADR-0008: Documentation site — MkDocs Material at docs.fmm.house

  • Status: Accepted
  • Date: 2026-07-19

Context

The repo's operational docs (runbooks, architecture.md, ADRs, gaming notes) had grown enough that reading raw .md or browsing the git tree was clumsy — no unified search, no navigation, no rendered cross-links. We wanted a browsable site at docs.fmm.house.

Constraints that shaped the choice: the repo lives on av (so a container can render it live with no CI/git-pull), we prefer no extra database, images are pinned, and *.fmm.house + Traefik mean a new hostname is zero DNS/TLS work (docs/runbooks/dns.md).

Options weighed (with the user):

  • Forgejo's built-in Markdown rendering — free, but no unified cross-file search/nav, and the repo isn't hosted on Forgejo yet.
  • Docsify — zero build, renders .md client-side; lighter but weaker search and a hand-curated sidebar.
  • Wiki.js — full wiki with in-browser editing + git sync, but needs Postgres, and the editing feature is redundant since docs are authored in git.
  • MkDocs Material — static-site generator purpose-built for exactly this Markdown-in-git case.

Decision

Adopt MkDocs Material (stacks/mkdocs, squidfunk/mkdocs-material pinned):

  • Bind-mount ./docs read-only; mkdocs serve live-reloads on change — no build step, no git pull. The site always reflects the working tree on av.
  • Auto-nav from the docs/ tree (new .md files appear with zero config), Material theme with search, mermaid, and light/dark. docs/index.md is the homepage.
  • Traefik Host(docs.fmm.house) on the *.fmm.house wildcard cert.
  • Image is Docker-Hub-only (no ghcr/ECR mirror), consistent with other mirror-less apps (peertube, ollama); Diun watch_repo alerts on new versions to bump the pin.

Consequences

  • New docs need no site work — drop a .md in docs/, it's in the sidebar and search.
  • mkdocs serve is a dev server (single worker, livereload websocket). Fine for a private, low-traffic, tailnet/LAN-only site; it is not hardened for public traffic (which we don't serve). If that ever changes, switch to mkdocs build + a static file server.
  • Root-level CONTEXT.md / AGENTS.md are not in the site — they live outside docs_dir and can't be nested into the read-only mount (Docker can't create a mountpoint under a ro bind). They remain browsable in the repo; they could be surfaced later via committed symlinks into docs/.
  • One more Traefik-fronted service; no database, no new secrets.