AI-chatbot met bronvermelding in Docusaurus 3

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 is het belangrijkste onderdeel. React Strict Mode kan effects tijdens development opnieuw mounten, en Docusaurus wijzigt routes zonder het document te vervangen. Deze controle maakt beide situaties idempotent.

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.
• https://fonts.googleapis.com in style-src en https://fonts.gstatic.com in font-src als het widgetfont nog niet beschikbaar is.
• 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 een vraag waarvoor geen ondersteuning is en controleer of de assistent terugvalt in plaats van een bron te verzinnen.
5. Test de launcher in een smalle mobiele viewport en controleer of deze de navigatie- of pagineringselementen niet afdekt.

De script-telling bewijst dat dubbele loaders worden voorkomen. Ze 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

• Installatiereferentie voor de ChattyBox-widget
• Docusaurus-documentatie over swizzling
• MDN-handleiding voor Content Security Policy