ADR-003: MkDocs Material als Dokumentationstool¶
| Feld | Wert |
|---|---|
| Status | accepted |
| Datum | 2026-03-20 |
| Betrifft | homelab-documentation |
Kontext¶
Fuer die zentrale Dokumentationsplattform wird ein Static Site Generator benoetigt, der 60+ technische Seiten uebersichtlich darstellt. Anforderungen:
- Offline-Volltextsuche (Doku ist privat, keine externen Suchdienste)
- Hierarchische Navigation mit Tabs und Sidebar
- Plugin fuer LikeC4-Diagramm-Integration
- Python-Stack bevorzugt (passt zur Raspberry Pi Entwicklungsumgebung)
- Ausgereiftes Projekt mit stabiler API
Entscheidung¶
MkDocs Material v9.7.x wird als Dokumentationstool eingesetzt. Das Projekt ist bereits im homeserver Repo im Einsatz — der Migrationsaufwand ist null.
Seit v9.7.0 sind alle ehemaligen Insiders-Features kostenlos verfuegbar.
Das mkdocs-likec4 Plugin (v1.1.1) bietet native Integration fuer
Architekturdiagramme.
Bekannte Einschraenkung: MkDocs (Basis-Framework) ist seit August 2024 ohne neues Release. Material for MkDocs befindet sich im Maintenance-Mode (Security-Fixes bis ca. November 2026). Der Maintainer entwickelt Zensical als Drop-in-Nachfolger.
Upgrade-Pfad: Migration auf Zensical als RFC planen, sobald es eine
stabile Version erreicht. Zensical liest mkdocs.yml nativ — minimaler
Migrationsaufwand erwartet.
Alternativen¶
| Option | Version | Ergebnis |
|---|---|---|
| Starlight (Astro) | v0.38.1 | Kein v1.0 erreicht, kein offizielles LikeC4-Plugin, Node.js-Stack statt Python. |
| Docusaurus (Meta) | v3.9.2 | Ueberdimensioniert fuer reine Doku, Offline-Suche nur via Community-Plugin, React-Overhead. |
| VitePress (Vue) | v2.0.0-alpha | Noch im Alpha-Stadium, keine Offline-Suche verfuegbar. |
Konsequenzen¶
Positiv:
- Null Migrationsaufwand — bestehende Konfiguration wiederverwendbar
- Eingebaute Offline-Volltextsuche (Lunr) ohne externe Abhaengigkeiten
- Exzellente Navigation fuer grosse Dokumentationen
- Python-Stack konsistent mit Entwicklungsumgebung
- Aktive Community, umfangreiche Plugin-Landschaft
Negativ:
- Basis-Framework ohne aktive Weiterentwicklung
- Migration auf Zensical mittelfristig noetig
- Markdown-Erweiterungen teilweise MkDocs-spezifisch (Lock-in)