Zum Hauptinhalt springen
ChattyBoxKostenlos starten

KI-Chatbot mit Quellenangaben für Docusaurus 3

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

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 schützt genau dieses Einfügen vor React-Remounts in der Entwicklung und clientseitigen Routenwechseln. Sie erkennt keinen separaten Loader mit einer anderen oder fehlenden ID; verwenden Sie nur eine Integration pro Seite.

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.ai in script-src für den Widget-Loader.
  • Den Ursprung Ihrer konfigurierten Chat-API in connect-src.
  • Für den Loader des aktuellen Quellcodes https://fonts.googleapis.com in style-src und https://fonts.gstatic.com in font-src, wenn er das Inter-Stylesheet einfügt. Ein passender Link zu einem Google-Fonts-Stylesheet verhindert dieses Einfügen; eine anderweitig verfügbare Schriftart allein nicht. Prüfen Sie das Verhalten des bereitgestellten Loaders.
  • Den Ursprung jedes konfigurierten benutzerdefinierten Icon-Bildes in img-src.
  • Inline-Komponentenstile in style-src fü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:

  1. Öffnen Sie zwei verschiedene Dokumentationsrouten, ohne den Browser vollständig zu aktualisieren.
  2. Führen Sie nach jeder Navigation document.querySelectorAll('#chattybox-widget').length aus. Der Wert muss 1 bleiben.
  3. Stellen Sie eine Frage, die von einer indexierten Seite beantwortet wird, und bestätigen Sie, dass die Antwort auf diese Seite verlinkt.
  4. Stellen Sie nicht unterstützte Fragen und beurteilen Sie, ob der Assistent auf eine Fallback-Antwort zurückgreift, statt eine Quelle zu erfinden; wiederholen Sie den Test mit repräsentativen Fällen, ohne anzunehmen, dass jede Antwort eine Auskunft verweigert.
  5. Testen Sie den Launcher in einem schmalen mobilen Viewport und prüfen Sie, dass er weder Navigation noch Paginierungssteuerelemente verdeckt.

Die Skriptzählung erfasst nur diese ID; ein separater Loader ohne ID oder mit einer anderen ID kann dennoch vorhanden sein. Prüfen Sie auch alle Integrationen und das dargestellte Widget. Die Zählung 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.

Quellen​