Hoppa till huvudinnehållet
ChattyBoxBörja gratis

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

· 4 min läsning
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 skyddar just denna infogning mot Reacts ommonteringar under utveckling och ruttändringar på klientsidan. Det upptäcker inte en separat laddare med ett annat eller saknat ID; använd bara en integration per sida.

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.
  • För laddaren i den aktuella källkoden: https://fonts.googleapis.com i style-src och https://fonts.gstatic.com i font-src när den injicerar stilmallen för Inter. En matchande länk till en Google Fonts-stilmall förhindrar injiceringen; att teckensnittet annars är tillgängligt räcker inte. Kontrollera hur den driftsatta laddaren fungerar.
  • Ursprunget för eventuell konfigurerad anpassad ikonbild i img-src.
  • 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 frågor som inte stöds och utvärdera om assistenten använder en reservåtgärd i stället för att hitta på en källa; upprepa med representativa fall utan att anta att varje svar avstår från att svara.
  5. Testa startknappen i en smal mobil viewport och kontrollera att den inte täcker navigerings- eller pagineringskontroller.

Kontrollen av skriptantalet räknar bara detta ID; en separat laddare utan ID eller med ett annat ID kan fortfarande finnas. Kontrollera även alla integrationer och den renderade widgeten. Antalet 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​