Files

T

Thore CimbalandClaude Fable 5 7d7c1e86b0 ADR-0006: Wikis ins Lab konsolidiert, Docusaurus als gemeinsame Leseflaeche

Drei auseinandergelaufene Dokustaende aufgeloest: Gitea-Wiki-Repo (gepflegt,
nicht gespiegelt), wiki-Branch (Mai-Abzug von docs/), docs/ im main. Wiki liegt
jetzt im GitLab-Wiki; homelab/wiki baut daraus + homelab/docs + diesem Repo eine
Docusaurus-Seite. Damit entfaellt die letzte direkt-zu-Gitea-Ausnahme.

CLAUDE.md + README entsprechend nachgezogen; Rollout-Restarbeit als #18,
Branch-Entscheidung als #19.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PKhFj1S3UdD6xL2fbWPeYj

2026-08-01 12:00:00 +00:00

3.3 KiB

Raw Blame History

0006 — Wikis ins Lab konsolidieren, Docusaurus als gemeinsame Lesefläche

Status: akzeptiert · Datum: 2026-08-02 · Entscheider: sorb

Kontext

Die Dokumentation lag an drei Orten mit drei Ständen, was beim Audit auffiel:

Gitea-Wiki-Repo …gitops.wiki.git — 15 Seiten, gepflegt bis 2026-07-31. Vom Push-Mirror nicht erfasst: ein Wiki ist ein eigenes Repo, kein Branch.
wiki-Branch im gitops-Repo — Stand 2026-05-14, mitgezogen, weil der Mirror alle Branches trägt. Inhalt: ein damaliger Abzug von docs/, kein gepflegtes Wiki.
docs/ im main-Branch — die eigentliche, laufend gepflegte Repo-Doku.

Dazu waren die GitLab-Wikis aller Projekte leer, und die Wiki-Inhalte enthielten sachlich falsche Aussagen (node-exporter-DaemonSet als aktive Komponente, obwohl am 2026-08-01 entfernt; Issues „in Gitea", obwohl migriert).

Entscheidung

Das Wiki zieht ins Lab und wird Teil der git.lab-Wahrheit: Die 15 Seiten liegen im GitLab-Wiki des gitops-Projekts (Wiki-Reiter). Damit entfällt die letzte „direkt-zu-Gitea"-Ausnahme aus ADR-0001.

Eine gemeinsame Lesefläche statt einer gemeinsamen Struktur: Das Repo homelab/wiki baut mit Docusaurus eine Seite unter wiki.lab, die drei Quellen nebeneinander zeigt — Plattform (gitops-Wiki), Homelab (homelab/docs), Arbeitsweise (management). Die Inhalte werden beim Bau eingesammelt; das Wiki-Repo enthält selbst keinen Text.

Konsequenzen

Änderungen gehören ins Quell-Repo, nie ins Wiki-Repo — was dort in content/ landet, wird beim nächsten Bau überschrieben.
Der Bau läuft in der Lab-CI (nur dort gibt es Lesezugriff auf die Quellen) und legt ein statisches Image in der Lab-Registry ab; Dokploy deployt es. Ein Pipeline-Zeitplan ist der eigentliche Aktualisierungsmechanismus: Das Wiki folgt den Quellen, ohne dass jemand im Wiki-Repo committen muss.
Voraussetzung: Jedes Quell-Repo muss das Wiki-Projekt in seinen Job token permissions freigeben.
Jede Quelle bleibt ohne dieses Tool lesbar (direkt im Repo oder in der GitLab-Oberfläche). Deshalb bringen die Quellen keine Docusaurus-Metadaten mit und .md wird als CommonMark statt MDX geparst.
Der wiki-Branch im gitops-Repo ist überholt. Er bleibt vorerst als Historie stehen, ist aber in README und CLAUDE.md ausdrücklich als „nicht die gepflegte Fassung" markiert. Löschen wäre sauberer — Entscheidung dazu steht aus (Issue #19).

Verworfene Alternativen

Alles in ein Repo verschmelzen: Die Quellen haben unterschiedliche Leser und Halbwertszeiten; eine gemeinsame Struktur hätte alle drei schlechter gemacht.
Wiki auf Gitea belassen: widerspricht ADR-0002 und hielt eine Ausnahme am Leben, die niemand mehr begründen konnte.
Inhalte per Submodule einbinden statt beim Bau klonen: Submodules hätten die Quellen an feste Commits gebunden — genau das Gegenteil von „das Wiki folgt den Quellen".
MkDocs/Wiki.js: Docusaurus gewählt wegen Multi-Instanz-Docs (die Bereiche nebeneinander) und weil es rein statisch ausliefert — kein Server, keine Datenbank, kein Betriebsaufwand.

3.3 KiB Raw Blame History