Dokumentieren mit dem Wiki

Neue Inhalte werden ausschließlich im Forgejo-Repository documentation-content angelegt. Ein erfolgreicher Release-Build übernimmt Navigation, Suche, Live-Wiki, statische HTML-Version und ZIP automatisch.

Standardablauf

Aktuelles main in einen frischen Branch oder Worktree holen.
_wiki/navigation.html, AGENTS.md und den Klassenvertrag lesen.
Die Seite am fachlich passenden, bestehenden Pfad anlegen.
Gültiges wiki-page/v1-Frontmatter beziehungsweise wiki-page-metadata einfügen.
Relative Links und Assets ergänzen; keine Secrets, PII oder externen Asset-Hotlinks einchecken.
Content-Build, Linkprüfung, HTML-Export, ZIP sowie Desktop- und Mobilansicht prüfen; bei LLM-Änderungen zusätzlich einen synthetischen quellengebundenen Ende-zu-Ende-Auftrag ausführen.
Commit reviewen, nach main bringen und ausschließlich über den Releaseprozess veröffentlichen.

Menüplatz festlegen

Eine normale Themenseite verwendet placement: main. topic verweist auf eines der zentral registrierten Haupttopics. parent verweist auf die ID einer anderen Seite im selben Topic; fehlt das Feld, liegt die Seite auf der ersten vertikalen Ebene.

---
wiki:
  schema: wiki-page/v1
  title: Telegram-Dienst
  summary: Architektur und Betrieb des Telegram-Supportdienstes.
  document_type: architecture
  status: active
  navigation:
    placement: main
    topic: uberspace
    id: telegram-service
    parent: services
    label: Telegram-Dienst
    order: 30
    pinned: false
    appearance: strong
  tags: [telegram, support, service]
  aliases: [telegram-bridge]
  audience: [developer, admin, codex]
  owner: infrastructure
  reviewed_at: "2026-08-27"
  toc: auto
  related:
    - operations/telegram-runbook.md
---

placement: footer ist ausschließlich für flache Wiki-interne Seiten gedacht. topic, parent und verschachtelte Footer-Einträge sind dort verboten. Mit placement: unlisted bleibt eine Seite über Links, Suche, CLI und MCP erreichbar, erscheint aber nicht im Menü.

Build stoppt absichtlich

Unbekannte Topics oder Appearance-IDs, doppelte IDs, fehlende Elternknoten, Zyklen, ungültige Related-Ziele und verschachtelte Footer-Seiten sind harte Fehler.

Reichhaltige Inhalte in Markdown

Tabellen

| Dienst | Status | URL |
| --- | --- | --- |
| Wiki | aktiv | `projects.webdevmedia.de/documentation` |
{.wiki-table-compact .wiki-table-striped .wiki-table-scroll}

Aufklappbare Warnungen und Lösungen

> **Warnsignal: Uneindeutiger Releasepfad**
>
> **Evidenz:** Mehrere historische Releases sind vorhanden.
>
> **Auswirkung:** Der aktive Stand kann falsch eingeordnet werden.
{.wiki-warning .wiki-collapsible}

> **Bereinigungsvorschlag**
>
> Releases anhand des aktiven Symlinks und der Git-Hashes klassifizieren.
{.wiki-tip .wiki-collapsible}

Für ein bestätigtes Problem wird .wiki-danger .wiki-collapsible verwendet. Die sichtbare Überschrift muss zusätzlich in Worten deutlich machen, ob es sich um ein Warnsignal, ein Problem oder einen Vorschlag handelt; Farbe allein reicht nicht.

Bilder, Diagramme, Karten und Status

![Architektur](images/architecture.svg){.wiki-image-full .wiki-image-bordered}

- [MCP-Endpunkte](../interfaces/mcp.md)
- [CLI-Befehle](../interfaces/cli.md)
{.wiki-grid-2}

**AKTIV**{.wiki-badge .wiki-status-ok}

SVG-Diagramme und Bilder werden lokal im Content-Repository abgelegt. Der vollständige Klassenumfang steht im CommonMark-Klassenvertrag.

Wann HTML sinnvoll ist

Aktives HTML ist für interaktive Werkzeuge, komplexe Visualisierungen oder individuelle dynamische Layouts vorgesehen. Das Dokument muss vollständiges HTML und ein JSON-Script mit der ID wiki-page-metadata enthalten. Relative CSS-, JavaScript-, Bild- und Datendateien bleiben im selben Content-Unterbaum.

Vertrauensgrenze

HTML, CSS, JavaScript und aktive SVGs besitzen Same-Origin-Rechte und werden deshalb wie Anwendungscode reviewt. Für überwiegend dokumentarische Inhalte bleibt Markdown die kleinere und sicherere Lösung.

Neue Haupttopics und individuelle Navigationseffekte werden in _wiki/navigation.html definiert. Die Datei darf geprüftes HTML, CSS und JavaScript enthalten. Jede Änderung benötigt einen dokumentierten SHA-256 und wird zusammen mit dem Content atomar veröffentlicht. Mit ?safe-ui=1 lädt das Live-Wiki die Kernnavigation ohne diese Erweiterungen.

AGENTS.md-Kernsektion für neue Codex-Sitzungen

Die folgende Sektion kann in einer übergeordneten AGENTS.md verwendet werden. Eine projektspezifische AGENTS.md darf Pfade und Prüfbefehle ergänzen, aber die Dokumentationspflicht nicht aufheben.

## Dokumentations-Wiki

Baue vor Infrastruktur-, MCP-, Codex- oder Supportarbeiten zuerst Wissen aus
dem produktiven Wiki unter `https://projects.webdevmedia.de/documentation/`
auf. Nutze je nach verfügbarer Oberfläche die Wiki-CLI, die
`documentation__*`-MCP-Tools oder die Wiki-API. Beginne mit Status,
Themenbaum, Suche und den relevanten Originalquellen. Nutze eine LLM-Frage nur
zur quellengebundenen Synthese; sie ersetzt nicht das Lesen der Quellen.

Pflege Wiki-Inhalte ausschließlich im Forgejo-Repository
`documentation-content`, in einem frischen Branch oder Worktree auf Basis von
aktuellem `main`. Bearbeite niemals `content/current`, Release- oder
Laufzeitverzeichnisse direkt.

Jede Änderung an Serverpfaden, Diensten, URLs, APIs, MCPs, OAuth,
Deployments, Rollbacks, Authentifizierung, Codex-Adaptern, Account-Auswahl,
Modellen oder Betriebsabläufen muss im selben Arbeitsauftrag auf der passenden
kanonischen Wiki-Seite reflektiert werden.

Änderungen an Wiki-Funktionen oder der Wiki-Struktur müssen zusätzlich im
Autorenhandbuch und in der Wiki-Architektur dokumentiert werden. Aktualisiere
je nach Änderung auch `_wiki/navigation.html`, LLM-Sitzungen, CLI, MCP,
URLs/Dienste oder den CommonMark-Klassenvertrag.

Jede Markdown-Seite benötigt `wiki-page/v1`-Frontmatter; jede eigenständige
HTML-Seite benötigt `wiki-page-metadata`. Nutze Markdown als Standard und
aktives HTML nur für echte Interaktion oder komplexe Visualisierungen.

Prüfe Titel, Summary, Navigation, Tags, Related-Links, Owner und
`reviewed_at`. Dokumentiere keine Secrets, Bearer, Zugangscodes, Cookies,
privaten Prompts oder personenbezogenen Accountdaten.

Vor Veröffentlichung müssen Content-Build, Navigation, Links, statische
HTML-Version, ZIP sowie die relevanten Desktop- und Mobilansichten erfolgreich
sein.

Statische HTML-Version

Der Headerlink HTML-Version öffnet die gerenderte Fassung. Erst dort steht ZIP herunterladen; der Live-Header enthält keinen direkten ZIP-Link. Alle internen Links des Exports sind relativ, sodass der entpackte Bestand direkt von HDD gelesen oder über einen lokalen HTTP-Server bereitgestellt werden kann.