AI-chattbot med källhänvisningar i Docusaurus 3

Efter den första sidladdningen fungerar Docusaurus som en single-page-applikation. En widgetintegration som bara fungerar i det ursprungliga dokumentet, eller som lägger till en andra laddare vid varje ruttändring, är inte redo för produktion. Den här guiden använder en stabil skriptidentitet och en temarot som förblir monterad på dokumentationsrutterna.

Författare och teknisk granskare: Michael Fisher, underhållsansvarig för ChattyBox. Publicerad och tekniskt granskad den 10 juli 2026. De reproducerbara kontrollerna nedan är en implementeringsguide, inte ett prestanda- eller noggrannhetsbenchmark.

1. Lägg till temakomponenten Root

Skapa src/theme/Root.tsx på din Docusaurus-webbplats:

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}</>;
}

Det stabila ID:t chattybox-widget är den viktiga delen. React Strict Mode kan montera om effekter under utvecklingen, och Docusaurus byter rutt utan att ersätta dokumentet. Skyddet gör båda fallen idempotenta.

Använd API-URL:en som visas av ditt ChattyBox-projekt i stället för att kopiera en exempelutgåva. Se referensen för widgetinstallation för aktuella attribut och Docusaurus produktguide för vägledning om källurval och utvärdering.

2. Låt laddaren vara monterad

Placera inte skriptet i en enskild dokumentationssida eller layout som Docusaurus ersätter under navigeringen. Den swizzlade Root-komponenten omsluter applikationen under hela dess livstid, så widgeten förblir tillgänglig när besökare rör sig mellan guider och referenssidor.

Om webbplatsen redan har src/theme/Root.tsx ska du slå ihop effekten med den befintliga komponenten i stället för att ersätta autentisering, analys eller andra providers.

3. Ta hänsyn till Content Security Policy

En restriktiv policy måste tillåta:

• https://chattybox.ai i script-src för widgetens laddningsskript.
• Ursprunget för ditt konfigurerade chatt-API i connect-src.
• https://fonts.googleapis.com i style-src och https://fonts.gstatic.com i font-src om widgetens teckensnitt inte redan är tillgängligt.
• Inline-komponentstilar i style-src för den aktuella widgetversionen.

Utgå från den befintliga policyn och lägg bara till de ursprung som faktiskt används. Ersätt inte en restriktiv policy med ett brett wildcard.

4. Reproducera integrationskontrollerna

Lägg till Root-wrappen ovan i ditt Docusaurus-projekt och kör:

bun install
bun run start

Kontrollera sedan:

1. Öppna två olika dokumentationsrutter utan att uppdatera webbläsaren helt.
2. Kör document.querySelectorAll('#chattybox-widget').length efter varje navigering. Värdet måste förbli 1.
3. Ställ en fråga som besvaras av en indexerad sida och bekräfta att svaret länkar till sidan.
4. Ställ en fråga som inte stöds och bekräfta att assistenten använder en reservåtgärd i stället för att hitta på en källa.
5. Testa startknappen i en smal mobil viewport och kontrollera att den inte täcker navigerings- eller pagineringskontroller.

Kontrollen av skriptantalet bevisar att dubbletter förhindras. Den bevisar inte kvaliteten på informationshämtningen. Använd en representativ uppsättning frågor och scraping-guiden för att validera källtäckningen före lanseringen.

Vad du bör övervaka efter lanseringen

Dokumentera obesvarade frågor, felaktiga källhänvisningar, inaktuella källsidor och rutter där startknappen skymmer webbplatsens kontroller. Testa igen efter uppgraderingar av Docusaurus-temat, eftersom ändringar i navigering och innehållslayout kan påverka placeringen även när laddaren fortfarande fungerar korrekt.

För en bredare lanseringsordning använder du checklistan för implementering av dokumentationschattbot och lanseringschecklistan.

Källor

• Referens för ChattyBox-widgetinstallation
• Docusaurus-dokumentation om swizzling
• MDN:s guide till Content Security Policy