KI-Chatbot mit Quellenangaben für MkDocs

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 ermöglicht außerdem eine direkte Prüfung auf doppelte Loader.

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

Führen Sie in Ihrem MkDocs-Projekt Folgendes aus:

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, und eine nicht unterstützte Frage führt zu einem vorsichtigen Fallback.

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 bei Bedarf die Schriftart-Ursprünge in style-src und font-src. 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

• Referenz zur Installation des ChattyBox-Widgets
• Anpassung von MkDocs-Themes
• Anpassung von Material for MkDocs
• MDN-Leitfaden zur Content Security Policy