Dokumentation bauen und veröffentlichen¶

Diese Seite beschreibt den Buildvorgang der MkDocs-Dokumentation. Sie ist bewusst unabhängig von Agenten-Skills gehalten, damit der Ablauf direkt auf dem Server nachvollziehbar bleibt.

Pfade¶

Zweck	Pfad
MkDocs-Konfiguration	`/opt/selfhost/mkdocs.yml`
Markdown-Quellen	`/opt/selfhost/docs/`
Build-Ausgabe / Webroot	`/opt/selfhost/site/`
MkDocs-Virtualenv	`/opt/selfhost/tools/mkdocs-venv/`
Build-Skript	`/opt/selfhost/docs/scripts/build-docs.sh`

Die Webseite wird aus /opt/selfhost/site/ ausgeliefert. Dieser Ordner ist ein Build-Artefakt und wird nicht von Hand bearbeitet.

Einmalige Installation / Aktualisierung der Build-Umgebung¶

MkDocs ist in einer lokalen virtuellen Python-Umgebung installiert. Falls diese Umgebung fehlt oder erneuert werden soll:

cd /opt/selfhost
python3 -m venv /opt/selfhost/tools/mkdocs-venv
/opt/selfhost/tools/mkdocs-venv/bin/pip install --upgrade pip
/opt/selfhost/tools/mkdocs-venv/bin/pip install --upgrade mkdocs mkdocs-material

Manueller Strict-Build¶

Nach Änderungen an der Dokumentation sollte immer ein Strict-Build ausgeführt werden:

cd /opt/selfhost
/opt/selfhost/tools/mkdocs-venv/bin/mkdocs build --strict

Wichtige Eigenschaften:

--strict bricht bei MkDocs-Warnungen ab.
Interne Markdown-Links werden dadurch geprüft.
Das Ergebnis landet gemäß mkdocs.yml unter /opt/selfhost/site/.
Externe Links werden dabei nicht vollständig als HTTP-Check geprüft.

Empfohlenes Build-Skript¶

Für den Normalfall gibt es ein fertiges Skript:

/opt/selfhost/docs/scripts/build-docs.sh

Das Skript prüft zuerst, ob die MkDocs-Umgebung vorhanden ist, baut anschließend strict und zeigt danach kurz den Ausgabeordner an.

Route der veröffentlichten Dokumentation¶

Die veröffentlichte Dokumentation ist als statische Caddy-Route über die Subdomain Registry definiert:

Feld	Wert
Route-ID	`serverdocs`
Hostname	`serverdocs.marcosudau.com`
Typ	`static`
Root	`/opt/selfhost/site`
Zugriff	Tailnet-only; außerhalb wird die OpenClaw-Hinweisseite angezeigt

Änderungen an der Route erfolgen nicht direkt in Caddy, sondern über /opt/selfhost/registry/routes.json und anschließend:

sudo /opt/selfhost/tools/selfhost-routes validate
sudo /opt/selfhost/tools/selfhost-routes generate --apply-homepage
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Nach einem erfolgreichen Build prüfen¶

# Lokale Dateien vorhanden?
test -f /opt/selfhost/site/index.html && echo ok

# Caddy-Konfiguration gültig?
sudo caddy validate --config /etc/caddy/Caddyfile

# Optional: HTTP-Header über Caddy prüfen, wenn DNS/Tailnet erreichbar ist
curl -I https://serverdocs.marcosudau.com/

Konventionen¶

Markdown-Quellen werden unter /opt/selfhost/docs/ gepflegt.
Die Navigation wird in /opt/selfhost/mkdocs.yml explizit gepflegt.
Neue Seiten sollten direkt in mkdocs.yml eingetragen werden, damit mkdocs build --strict fehlende Dateien oder defekte Links früh findet.
Secrets, Passwörter, API-Keys und Tokens werden nie in der Dokumentation ausgeschrieben.