Ga naar de hoofdinhoud
ChattyBoxStart gratis

AI-chatbot met bronvermelding in Docusaurus 3

· 4 min lezen
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

Docusaurus gedraagt zich na de eerste paginalading als een singlepage-applicatie. Een widgetintegratie die alleen op het eerste document werkt, of bij elke routewijziging een tweede loader toevoegt, is niet klaar voor productie. Deze handleiding gebruikt een stabiele scriptidentiteit en een thema-root die gemonteerd blijft op alle documentatieroutes.

Auteur en technisch reviewer: Michael Fisher, maintainer van ChattyBox. Gepubliceerd en technisch gecontroleerd op 10 juli 2026. De reproduceerbare controles hieronder zijn een implementatiehandleiding, geen benchmark voor prestaties of nauwkeurigheid.

1. Voeg de thema-component Root toe​

Maak src/theme/Root.tsx aan in je Docusaurus-site:

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

De stabiele chattybox-widget-ID beschermt deze specifieke invoeging tegen React-hermontages tijdens development en client-side routewijzigingen. De controle detecteert geen afzonderlijke loader met een andere of ontbrekende ID; gebruik slechts één integratie per pagina.

Gebruik de API-URL die in je ChattyBox-project wordt weergegeven in plaats van een voorbeelddeployment te kopiëren. Bekijk de installatiereferentie voor de widget voor de huidige attributen en de Docusaurus-producthandleiding voor richtlijnen over bronselectie en evaluatie.

2. Houd de loader gemonteerd​

Plaats dit script niet in een afzonderlijke documentatiepagina of layout die Docusaurus tijdens de navigatie vervangt. De door swizzling aangepaste Root-component omhult de applicatie gedurende de hele levensduur, zodat de widget beschikbaar blijft terwijl bezoekers tussen handleidingen en referenties navigeren.

Als je site al src/theme/Root.tsx heeft, voeg het effect dan samen met de bestaande component in plaats van authenticatie-, analytics- of andere providers te vervangen.

3. Houd rekening met Content Security Policy​

Een restrictief beleid moet het volgende toestaan:

  • https://chattybox.ai in script-src voor de widget-loader.
  • De geconfigureerde chat-API-origin in connect-src.
  • Voor de loader uit de huidige broncode: https://fonts.googleapis.com in style-src en https://fonts.gstatic.com in font-src wanneer deze het Inter-stylesheet injecteert. Een overeenkomende link naar een Google Fonts-stylesheet voorkomt die injectie; alleen een beschikbaar font is daarvoor niet voldoende. Controleer het gedrag van de uitgerolde loader.
  • De origin van een eventueel geconfigureerde aangepaste pictogramafbeelding in img-src.
  • Inline componentstijlen in style-src voor de huidige widget-build.

Begin met je bestaande beleid en voeg alleen origins toe die je daadwerkelijk gebruikt. Vervang een restrictief beleid niet door een brede wildcard.

4. Herhaal de integratiecontroles​

Voeg de bovenstaande Root-wrapper toe aan je Docusaurus-project en voer uit:

bun install
bun run start

Controleer vervolgens het volgende:

  1. Open twee verschillende documentatieroutes zonder de browser volledig te vernieuwen.
  2. Voer na elke navigatie document.querySelectorAll('#chattybox-widget').length uit. Dit moet 1 blijven.
  3. Stel een vraag die door een geïndexeerde pagina wordt beantwoord en controleer of het antwoord naar die pagina verwijst.
  4. Stel niet-ondersteunde vragen en beoordeel of de assistent terugvalt in plaats van een bron te verzinnen; herhaal dit met representatieve gevallen zonder aan te nemen dat de assistent altijd afziet van een antwoord.
  5. Test de launcher in een smalle mobiele viewport en controleer of deze de navigatie- of pagineringselementen niet afdekt.

De script-telling telt alleen die ID; er kan nog steeds een afzonderlijke loader zonder ID of met een andere ID aanwezig zijn. Controleer ook alle integraties en de weergegeven widget. De telling bewijst niet de kwaliteit van de retrieval. Gebruik een representatieve reeks vragen en de scrapinghandleiding om de brondekking vóór de lancering te valideren.

Wat je na de lancering moet monitoren​

Leg onopgeloste vragen, onjuiste bronvermeldingen, verouderde bronpagina's en routes vast waarop de launcher sitebesturingselementen afdekt. Test opnieuw na upgrades van het Docusaurus-thema, omdat wijzigingen in navigatie en contentlayout de plaatsing kunnen beïnvloeden, ook wanneer de loader correct blijft werken.

Gebruik voor een bredere uitrolvolgorde de implementatiechecklist voor een documentatiechatbot en de lanceringschecklist.

Bronnen​