RFC-001: Migration auf Zensical¶

Feld	Wert
Status	draft
Datum	2026-03-21
Betrifft	homelab-documentation
Tracking-Issues	noch keine

Problem¶

MkDocs (das Basis-Framework hinter Material for MkDocs) ist seit August 2024 unmaintained. Material for MkDocs befindet sich im Maintenance-Mode und wird voraussichtlich bis ca. November 2026 mit Sicherheitsupdates versorgt.

Fuer den langfristigen Betrieb der Homelab-Dokumentation ist eine aktiv gewartete Alternative notwendig. Ohne Wechsel drohen Sicherheitsluecken in Abhaengigkeiten und fehlende Kompatibilitaet mit neueren Python-Versionen.

Vorschlag¶

Migration auf Zensical, den offiziellen Drop-in-Nachfolger von squidfunk (dem Entwickler von Material for MkDocs). Zensical liest mkdocs.yml nativ und verspricht minimalen Migrationsaufwand fuer bestehende Material-for-MkDocs-Projekte.

Die Migration soll erst erfolgen, wenn eine stabile Version verfuegbar ist. Bis dahin bleibt Material for MkDocs im Einsatz.

Betroffene Repos¶

Repo	Aenderung
homelab-documentation	`mkdocs.yml` bleibt, Build-Tooling auf Zensical umstellen, Dockerfile anpassen
docker-images	MkDocs-Build-Image (`ghcr.io/swatpeacekeeper/mkdocs:latest`) auf Zensical umbauen
homeserver	Falls dort noch MkDocs-Reste existieren, ebenfalls migrieren

Umsetzungsschritte¶

Zensical Alpha/Beta in einer lokalen Testumgebung evaluieren
Plugin-Kompatibilitaet pruefen, insbesondere mkdocs-likec4
Build-Pipeline anpassen: Dockerfile und GitHub Actions Workflow
Staging-Deploy auf Cloudflare Pages testen
Migration durchfuehren und Material for MkDocs entfernen

Risiken¶

Risiko	Mitigation
Alpha-Software mit Breaking Changes	Erst bei stabiler Version migrieren, vorher nur testen
Plugin-Inkompatibilitaet (mkdocs-likec4)	Fruehzeitig testen, ggf. Plugin-Maintainer kontaktieren
Neue Bugs im Rendering	Staging-Deploy vor Produktions-Umstellung pruefen
Zeitdruck durch MkDocs-EOL	Material-Maintenance-Mode laeuft bis ~November 2026, genuegend Puffer