An der Dokumentation mitarbeiten¶

Diese Dokumentation ist selbst Open Source und lebt im Repository mandariOSS/docs. Sie wird mit MkDocs und dem Theme Material for MkDocs gebaut und als statische Seite ausgeliefert.

Kleine Korrektur¶

Jede Seite hat oben rechts einen Stift. Er öffnet die Markdown-Datei direkt auf GitHub, wo du sie im Browser ändern und als Pull Request einreichen kannst. Ein GitHub-Konto genügt.

Größere Änderung¶

git clone https://github.com/mandariOSS/docs.git
cd docs
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
mkdocs serve                                        # http://127.0.0.1:8000 mit Live-Reload

Vor dem Einreichen:

mkdocs build --strict

Der strikte Build schlägt bei defekten internen Links, fehlenden Seiten in der Navigation oder unbekannten Ankern fehl. Dieselbe Prüfung läuft in der CI, dazu ein Offline-Link-Check über das gebaute HTML, eine Prüfung der llms.txt und ein Test des fertigen Containers (Doku-Seiten und Weiterleitungen).

Die Prüfung der llms.txt kannst du nach dem Build auch lokal ausführen:

python tests/llms_txt.py --site site

Struktur¶

docs/
├── index.md              Startseite
├── plattform.md, glossar.md, aenderungen.md
├── insight/              Bürgerportal
├── work/                 Fraktionen
├── session/              Verwaltung
├── betrieb/              Self-Hosting, Konfiguration, Cron, Quellen, Monitoring
├── datenschutz/          TOM, Löschkonzept, AVV, Ingestor
├── entwicklung/          Code, Mitarbeit, SBOM
└── llms.txt              Übersicht für Sprachmodelle
mkdocs.yml                Navigation, Theme, Plugins
overrides/                Template-Anpassungen
nginx.conf                Auslieferung und Weiterleitungen
tests/                    CI-Prüfungen für llms.txt und den nginx-Container

Neue Seiten müssen in der Navigation in mkdocs.yml und in docs/llms.txt eingetragen werden. Jede Seite beginnt mit einem Frontmatter aus title und description, die Beschreibung erscheint in Suchmaschinen und Vorschauen.

Konventionen¶

Sprache: Deutsch. Leserinnen und Leser werden mit „du“ bzw. „ihr“ angesprochen, mandari spricht von sich als „wir“.
Zielgruppe zuerst: Jeder Bereich beginnt mit einer Übersichtsseite, die erklärt, für wen die Inhalte sind.
Nichts Internes: Keine Zugangsdaten, keine internen Hostnamen, keine Produktnamen von Hosting-Anbietern, keine Preisdetails. Preise stehen ausschließlich auf mandari.de/preise/.
Konkrete Befehle in Codeblöcken, Platzhalter in spitzen Klammern wie <kommune>.
Hinweiskästen sparsam: !!! info, !!! tip, !!! warning, !!! danger für wirklich Wichtiges.
Relative Links zwischen Seiten (../betrieb/cron.md), damit der strikte Build sie prüfen kann.

Was wo hingehört¶

Erklärungen für Nutzerinnen, Betreiber und Integratoren gehören hierher. Implementierungsnotizen, Dateipfade und Entwicklerdetails bleiben im Quellcode-Repository, dort im Verzeichnis docs/ und in CLAUDE.md. Wenn ein Feature im Hauptrepository dokumentiert wird, gehört eine für Außenstehende verständliche Fassung in diese Dokumentation.

Technische Details der Plattform¶

Suche: clientseitig, deutsch, ohne externen Dienst
Keine externen Ressourcen: Systemschriften, keine Web-Fonts, kein Tracking
Auslieferung: Docker-Image mit statischem Build hinter einem unprivilegierten nginx, gebaut und veröffentlicht durch GitHub Actions bei jedem Push auf main
llms.txt: kompakte Übersicht für Sprachmodelle nach llmstxt.org, gepflegt in docs/llms.txt. Neue Seiten trägst du dort im passenden Abschnitt ein; die CI prüft, dass jede Seite verlinkt ist und jeder Link auf eine vorhandene Seite zeigt.
Weiterleitungen: Alte Adressen der Anwendung, die Suchmaschinen noch unter docs.mandari.de kennen (etwa /insight/vorgaenge/<id>/ oder /oparl/v1/…), leitet nginx dauerhaft auf mandari.de weiter. Die CI startet den Container und prüft die Pfade aus tests/nginx_pfade.txt sowie jede gebaute Seite.
Lizenz: Inhalte CC BY 4.0, Build-Code MIT