MkDocs
Übersicht
MkDocs wird verwendet, um diese Dokumentation aus Markdown-Dateien als Webseite bereitzustellen.
Offizielle Dokumentation:
Lokale Vorschau
Die Dokumentation kann lokal oder auf dem Server mit Docker gestartet werden:
docker compose up -d
Danach ist MkDocs intern auf Port 8000 erreichbar.
Inhalte bearbeiten
Neue Seiten werden als Markdown-Dateien im Ordner docs/ angelegt.
Beispiel:
docs/services/forgejo.md
Bilder werden im Ordner docs/assets/images/ abgelegt.
Ein Bild kann so eingebunden werden:
Navigation
Die Navigation wird in der Datei mkdocs.yml gepflegt.
Beispiel:
nav:
- Start: index.md
- MkDocs: mkdocs.md
- Services:
- Übersicht: services/index.md
- Forgejo: services/forgejo.md
Aktualisierung
Nach Änderungen:
git add .
git commit -m "Update documentation"
git push
Auf dem Server:
git pull
docker compose restart docs
Best Practices
- öffentliche und private Dokumentation trennen
- keine Zugangsdaten dokumentieren
- keine internen Pfade veröffentlichen
- Bilder im Repository ablegen
- Seiten aus Sicht der Verwender schreiben
- technische Details nur dort nennen, wo sie für die Nutzung notwendig sind