KI-Chatbot mit Quellenangaben für Docusaurus 3
Docusaurus verhält sich nach dem ersten Seitenaufruf wie eine Single-Page-Anwendung. Eine Widget-Integration, die nur im initialen Dokument funktioniert oder bei jedem Routenwechsel einen zweiten Loader anhängt, ist nicht produktionsreif. Dieser Leitfaden verwendet eine stabile Script-ID und eine Theme-Root, die über die Dokumentationsrouten hinweg gemountet bleibt.
Autor und technischer Prüfer: Michael Fisher, Maintainer von ChattyBox. Veröffentlicht und technisch geprüft am 10. Juli 2026. Die folgenden reproduzierbaren Prüfungen sind ein Implementierungstutorial und kein Benchmark für Leistung oder Genauigkeit.
1. Die Root-Theme-Komponente hinzufügen
Erstellen Sie src/theme/Root.tsx in Ihrer Docusaurus-Website:
import React, { useEffect, type ReactNode } from 'react';
const WIDGET_ID = 'chattybox-widget';
export default function Root({ children }: { children: ReactNode }) {
useEffect(() => {
if (document.getElementById(WIDGET_ID)) return;
const script = document.createElement('script');
script.id = WIDGET_ID;
script.src = 'https://chattybox.ai/widget.js';
script.async = true;
script.dataset.apiKey = 'YOUR_API_KEY';
script.dataset.apiUrl = 'YOUR_CHAT_API_URL';
script.dataset.chattyboxWidget = 'true';
document.body.appendChild(script);
}, []);
return <>{children}</>;
}
Die stabile ID chattybox-widget ist der entscheidende Teil. React Strict Mode kann Effekte während der Entwicklung erneut mounten, und Docusaurus wechselt Routen, ohne das Dokument zu ersetzen. Die Schutzabfrage macht beide Fälle idempotent.
Verwenden Sie die von Ihrem ChattyBox-Projekt angezeigte API-URL, statt eine Beispielbereitstellung zu kopieren. Die Referenz zur Widget-Installation enthält die aktuellen Attribute. Im Docusaurus-Produktleitfaden finden Sie Hinweise zur Quellenauswahl und Evaluierung.
2. Den Loader dauerhaft eingebunden halten
Platzieren Sie dieses Script nicht in einer einzelnen Dokumentationsseite oder einem Layout, das Docusaurus bei der Navigation ersetzt. Die geswizzelte Root-Komponente umschließt die Anwendung für deren gesamte Lebensdauer, sodass das Widget verfügbar bleibt, wenn Besucher zwischen Leitfäden und Referenzen wechseln.
Wenn Ihre Website bereits src/theme/Root.tsx enthält, führen Sie den Effekt mit der vorhandenen Komponente zusammen, statt die Authentifizierung, Analytics oder andere Provider zu ersetzen.
3. Content Security Policy berücksichtigen
Eine restriktive Richtlinie muss Folgendes erlauben:
https://chattybox.aiinscript-srcfür den Widget-Loader.- Den Ursprung Ihrer konfigurierten Chat-API in
connect-src. https://fonts.googleapis.cominstyle-srcundhttps://fonts.gstatic.cominfont-src, falls die Widget-Schriftart nicht bereits verfügbar ist.- Inline-Komponentenstile in
style-srcfür den aktuellen Widget-Build.
Gehen Sie von Ihrer bestehenden Richtlinie aus und ergänzen Sie nur die Ursprünge, die Sie tatsächlich verwenden. Ersetzen Sie keine restriktive Richtlinie durch einen großzügigen Wildcard-Eintrag.
4. Integrationsprüfungen reproduzieren
Fügen Sie in Ihrem Docusaurus-Projekt den obigen Root-Wrapper hinzu und führen Sie Folgendes aus:
bun install
bun run start
Prüfen Sie anschließend:
- Öffnen Sie zwei verschiedene Dokumentationsrouten, ohne den Browser vollständig zu aktualisieren.
- Führen Sie nach jeder Navigation
document.querySelectorAll('#chattybox-widget').lengthaus. Der Wert muss1bleiben. - Stellen Sie eine Frage, die von einer indexierten Seite beantwortet wird, und bestätigen Sie, dass die Antwort auf diese Seite verlinkt.
- Stellen Sie eine nicht unterstützte Frage und bestätigen Sie, dass der Assistent auf eine Fallback-Antwort zurückgreift, statt eine Quelle zu erfinden.
- Testen Sie den Launcher in einem schmalen mobilen Viewport und prüfen Sie, dass er weder Navigation noch Paginierungssteuerelemente verdeckt.
Die Skriptzählung weist nach, dass Duplikate verhindert werden. Sie belegt nicht die Qualität des Retrievals. Verwenden Sie einen repräsentativen Fragensatz und den Scraping-Leitfaden, um die Quellenabdeckung vor dem Launch zu validieren.
Was nach dem Launch überwacht werden sollte
Erfassen Sie ungelöste Fragen, falsche Zitate, veraltete Quellseiten und Routen, auf denen der Launcher Steuerelemente der Website verdeckt. Testen Sie nach Upgrades des Docusaurus-Themes erneut, da Änderungen an Navigation und Inhaltslayout die Positionierung beeinflussen können, auch wenn der Loader weiterhin korrekt funktioniert.
Für eine umfassendere Rollout-Reihenfolge verwenden Sie die Checkliste zur Implementierung eines Dokumentations-Chatbots und die Launch-Checkliste.