Zum Hauptinhalt springen
ChattyBoxKostenlos starten

KI-Chatbot mit Quellenangaben für MkDocs

· 4 Minuten Lesezeit
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

MkDocs-Themes stellen unterschiedliche Override-Verzeichnisse bereit, und Material kann zwischen Seiten navigieren, ohne vollständig neu zu laden. Eine dauerhafte Integration muss die vorhandenen Theme-Skripte bewahren, das Widget einmal laden und mit Suche und Navigation auf Mobilgeräten zusammenarbeiten.

Autor und technischer Prüfer: Michael Fisher, Maintainer von ChattyBox. Veröffentlicht und technisch geprüft am 10. Juli 2026. Das folgende Prüfprotokoll ist ein Implementierungstutorial; es wird kein Ergebnis zu Traffic, Entlastung oder Antwortgenauigkeit behauptet.

1. Das richtige Override-Verzeichnis auswählen​

Für Material for MkDocs setzen Sie custom_dir auf ein overrides-Verzeichnis:

site_name: My documentation
theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.instant

Für das integrierte Theme verwenden Sie ein separates benutzerdefiniertes Theme-Verzeichnis:

site_name: My documentation
theme:
  name: mkdocs
  custom_dir: custom_theme

Durch die getrennte Aufbewahrung der Varianten bleibt klar, welches zugrunde liegende Upstream-Basistemplate erweitert wird.

2. Den scripts-Block erweitern​

Erstellen Sie overrides/main.html für Material oder custom_theme/main.html für das integrierte Theme:

{% extends "base.html" %}

{% block scripts %}
  {{ super() }}
  <script
    id="chattybox-widget"
    src="https://chattybox.ai/widget.js"
    async
    data-api-key="YOUR_API_KEY"
    data-api-url="YOUR_CHAT_API_URL"
    data-chattybox-widget="true"
  ></script>
{% endblock %}

{{ super() }} bewahrt die vom Theme bereitgestellten Skripte, einschließlich des Verhaltens von Navigation und Suche. Wenn es weggelassen wird, kann das Widget scheinbar funktionieren, während die Dokumentationsoberfläche unbemerkt beschädigt wird. Die stabile ID hilft, dieses Skript zu zählen; sie erkennt keinen anderen Loader mit einer anderen oder fehlenden ID.

Verwenden Sie projektspezifische Werte aus der Referenz zur Widget-Installation. Der MkDocs-Leitfaden für KI-Chatbots behandelt den Quellumfang, das Crawl-Verhalten und die Fragen, die vor der Veröffentlichung evaluiert werden sollten.

3. Beide Varianten bauen​

Laden Sie die MkDocs-Beispiele herunter, entpacken Sie sie und führen Sie diese Befehle im entpackten Verzeichnis examples/mkdocs-chattybox aus. Es enthält requirements.txt und die separaten Projekte material und vanilla. Verwenden Sie bei einem bestehenden Projekt stattdessen dessen eigene Abhängigkeiten und dessen Projektverzeichnis.

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

--strict wandelt Warnungen in Fehler um. Dadurch werden Probleme mit Navigation und Konfiguration erkannt, bevor das Widget evaluiert wird.

4. Browserprüfungen ausführen​

Stellen Sie jede Variante bereit und prüfen Sie:

  1. Die integrierte Suche wird weiterhin geöffnet und liefert das erwartete Dokumentationsergebnis.
  2. Die Instant-Navigation von Material wechselt die Route, ohne den Widget-Loader zu duplizieren.
  3. document.querySelectorAll('#chattybox-widget').length bleibt nach mehreren Routenwechseln 1.
  4. Bei einem Viewport von 390 px verdeckt der Launcher weder Suche und Navigation noch die Steuerelemente für vorherige/nächste Seite.
  5. Eine unterstützte Frage verweist auf die erwartete Seite; testen Sie nicht unterstützte Fragen auf vorsichtiges Fallback-Verhalten, ohne anzunehmen, dass jede Antwort eine Auskunft verweigert.

Die ID-Zählung erfasst nur dieses Skript; prüfen Sie auch andere Integrationen und das dargestellte Widget auf Duplikate. Die ersten vier Prüfungen validieren das Integrationsverhalten. Die fünfte hängt von den indexierten Seiten ab und erfordert einen repräsentativen Evaluierungsdatensatz. Folgen Sie dem Scraping-Leitfaden und der Launch-Checkliste, statt einen erfolgreichen Script-Ladevorgang als Beweis für Antwortqualität zu betrachten.

5. Eine restriktive CSP bewahren​

Erlauben Sie den Widget-Host in script-src, den konfigurierten API-Ursprung in connect-src und den Ursprung jedes benutzerdefinierten Icon-Bildes in img-src. Erlauben Sie für Widget v16 im aktuellen Quellcode die Google-Fonts-Ursprünge in style-src und font-src, wenn dessen Inter-Stylesheet eingefügt wird; prüfen Sie das Verhalten des bereitgestellten Loaders. Das aktuelle Widget fügt Komponentenstile ein. Daher benötigt auch eine ansonsten strenge Richtlinie eine explizite Strategie für Inline-Stile. Vermeiden Sie Wildcard-Quelllisten.

Wartungscheckliste​

Bauen Sie beide Theme-Varianten nach Upgrades von MkDocs oder Material neu, da sich die Namen der Upstream-Template-Blöcke ändern können. Halten Sie die Script-ID stabil, bewahren Sie super() und führen Sie die Prüfungen für Suche, Instant-Navigation, Überlappungen auf Mobilgeräten und Quellenangaben erneut aus.

Für die Planung des vollständigen Rollouts verwenden Sie die Checkliste zur Implementierung eines Dokumentations-Chatbots.

Quellen​