Wie das Docs-System funktioniert

Hinter den Kulissen

Diese Seite erklärt, wie das OpenClaw-Dokumentationssystem intern funktioniert. Nützlich für alle, die Dokumentation hinzufügen oder aktualisieren wollen, oder einfach die technische Umsetzung verstehen möchten.

Markdown-Dateien

Alle Dokumentation wird als Markdown-Dateien geschrieben, die im Repository unter folgendem Pfad gespeichert sind:

content/openclaw/docs/
├── en/              # Englische Dokumentation
│   ├── overview/
│   ├── getting-started/
│   ├── instances/
│   ├── channels/
│   ├── configuration/
│   ├── addons/
│   ├── billing/
│   ├── advanced/
│   ├── security/
│   ├── troubleshooting/
│   ├── use-cases/
│   ├── support/
│   └── meta/
└── de/              # Deutsche Dokumentation
    ├── overview/
    ├── getting-started/
    ├── instances/
    ├── channels/
    ├── configuration/
    ├── addons/
    ├── billing/
    ├── advanced/
    ├── security/
    ├── troubleshooting/
    ├── use-cases/
    ├── support/
    └── meta/

Jede Dokumentationsseite existiert als zwei Dateien: eine in en/ und eine in de/. Beide Versionen brauchen denselben Slug und dieselbe Kategorie.

YAML-Frontmatter

Jede Markdown-Datei beginnt mit einem YAML-Frontmatter-Block, der Metadaten definiert:

---
title: Seitentitel
slug: seiten-slug
category: getting-started
section: Erste Schritte
position: 3
---

Kategorie- und Sektions-Zuordnung

Dokument-Sync-Prozess

Dokumentationsdateien werden über den DocumentSyncService mit der Datenbank synchronisiert. Dieser Service:

1. Durchsucht das Verzeichnis content/openclaw/docs/ nach Markdown-Dateien
2. Parst YAML-Frontmatter aus jeder Datei
3. Konvertiert den Markdown-Inhalt zu HTML
4. Berechnet eine geschätzte Lesezeit
5. Generiert ein Vektor-Embedding für die semantische Suche
6. Speichert alles in der Datenbank

Der Sync-Ablauf

Markdown-Datei auf der Festplatte
  → System liest die Datei
  → YAML-Frontmatter wird für Metadaten geparst
  → Markdown-Body wird zu HTML konvertiert
  → Lesezeit wird aus der Wortanzahl berechnet
  → Text wird an die Embedding-API gesendet (4096 Dimensionen)
  → Datensatz wird in der Datenbank gespeichert

Datenbank-Felder

Jedes synchronisierte Dokument erzeugt einen Datensatz mit:

Semantische Suche mit pgvector

Das Dokumentationssystem nutzt Vektor-Embeddings für semantische Suche. Wenn du eine Frage stellst, passiert Folgendes:

1. Konvertiert die Frage in ein Vektor-Embedding mit demselben Embedding-Modell
2. Fragt die Dokumentationsdatenbank mittels Vektor-Ähnlichkeitssuche ab
3. Gibt die relevantesten Dokumentationsseiten zurück, sortiert nach Ähnlichkeit

Das bedeutet, dass du Dokumentation finden kannst, indem du in natürlicher Sprache beschreibst, wonach du suchst. Du brauchst keine exakten Schlüsselwörter oder Seitentitel.

Wie sich Vektorsuche von Textsuche unterscheidet

Textsuche findet exakte oder unscharfe Wortübereinstimmungen. Eine Suche nach "Server startet nicht" würde nur Seiten finden, die genau diese Wörter enthalten.

Vektorsuche versteht Bedeutung. Eine Suche nach "Server startet nicht" würde auch Seiten über "Instanz läuft nicht" oder "Deployment fehlgeschlagen" finden, weil die Konzepte semantisch ähnlich sind.

Verlinkung zwischen Seiten

Dokumentationsseiten verlinken aufeinander im /docs/slug-Format:

Siehe die [Architekturübersicht](/docs/architecture) für weitere Details.

Der Slug in der URL muss mit dem slug-Feld im Frontmatter der Zielseite übereinstimmen. Links funktionieren sprachübergreifend. Das System löst die korrekte lokalisierte Version basierend auf der Spracheinstellung des Lesers auf.

Neue Dokumentation hinzufügen

Um eine neue Dokumentationsseite hinzuzufügen:

1. Erstelle die englische Datei im entsprechenden Kategorie-Verzeichnis
2. Erstelle die deutsche Datei im passenden DE-Kategorie-Verzeichnis
3. Setze übereinstimmende Slugs. Beide Dateien müssen denselben slug-Wert haben
4. Wähle eine Position. Wähle eine Nummer, die die Seite in der richtigen Sortierreihenfolge innerhalb ihrer Kategorie platziert
5. Schreibe den Inhalt. Verwende Standard-Markdown mit Überschriften, Tabellen, Codeblöcken und Listen
6. Füge einen Abschnitt "Verwandte Dokumentation" hinzu. Verlinke am Ende auf andere relevante Seiten

Dateibenennungs-Konvention

Verwende den Slug als Dateinamen mit der Endung .md:

content/openclaw/docs/en/advanced/meine-neue-seite.md
content/openclaw/docs/de/advanced/meine-neue-seite.md

Beide Dateien hätten slug: meine-neue-seite in ihrem Frontmatter.

Inhaltsrichtlinien

• Schreibe in klarer, direkter Sprache
• Verwende Überschriften zur Gliederung des Inhalts (beginne mit ##, nicht mit #)
• Füge Codebeispiele ein, wo sie hilfreich sind
• Nutze Tabellen zum Vergleichen von Optionen oder Auflisten von Konfigurationen
• Beende jede Seite mit einem Abschnitt "Verwandte Dokumentation", der auf verwandte Seiten verlinkt
• Verwende keine unüberprüfbaren Behauptungen oder erfundenen Statistiken

Hinweise zur deutschen Übersetzung

Die deutsche Version sollte eine natürliche deutsche Übersetzung sein, keine wörtliche Übertragung:

• Verwende korrekte deutsche Umlaute (ä, ö, ü, ß), niemals ae, oe, ue, ss als Ersatz
• Lokalisiere die Felder title und section
• Behalte technische Begriffe (Docker, API, SSH) unverändert
• Übersetze Code-Kommentare, wenn sie nutzersichtbaren Text enthalten
• Verwende "du" (informell) für die Ansprache des Lesers

Qualitätssicherung

Das Dokumentationssystem umfasst automatisierte Prüfungen, die Folgendes überprüfen:

1. Jede Markdown-Datei enthält alle erforderlichen Frontmatter-Felder
2. Slugs sind eindeutig und konsistent zwischen Sprachversionen
3. Dateien synchronisieren erfolgreich mit der Datenbank
4. Inhalte sind korrekt formatiert und zugänglich

Verwandte Dokumentation

• Architekturübersicht. Technische Architektur der Plattform
• Best Practices. Empfehlungen für die effektive Nutzung von OpenClaw