2026-08-01 12:00:00 +00:00
|
|
|
# 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:
|
|
|
|
|
|
|
|
|
|
1. **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.
|
|
|
|
|
2. **`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.
|
|
|
|
|
3. **`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](0001-gitlab-kanonisch-push-mirror.md).
|
|
|
|
|
|
|
|
|
|
**Eine gemeinsame Lesefläche statt einer gemeinsamen Struktur:** Das Repo
|
|
|
|
|
[`homelab/wiki`](https://git.lab/homelab/wiki) baut mit Docusaurus eine Seite unter
|
2026-08-02 12:00:00 +00:00
|
|
|
`axionwiki.lab`, die drei Quellen **nebeneinander** zeigt — Plattform (gitops-Wiki),
|
2026-08-01 12:00:00 +00:00
|
|
|
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](https://git.lab/axion1337.chat/management/-/issues/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.
|
