Chatbot IA avec citations pour Docusaurus 3

Après le premier chargement, Docusaurus se comporte comme une application monopage. Une intégration de widget qui ne fonctionne que sur le document initial, ou qui ajoute un deuxième chargeur à chaque changement de route, n’est pas prête pour la production. Ce guide utilise une identité de script stable et une racine de thème qui reste montée sur l’ensemble des routes de documentation.

Auteur et relecteur technique : Michael Fisher, mainteneur de ChattyBox. Publié et vérifié techniquement le 10 juillet 2026. Les vérifications reproductibles ci-dessous constituent un tutoriel d’implémentation, et non un benchmark de performance ou de précision.

1. Ajouter le composant de thème Root

Créez src/theme/Root.tsx dans votre site Docusaurus :

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

L’identifiant stable chattybox-widget est l’élément essentiel. React Strict Mode peut remonter les effets pendant le développement, et Docusaurus change de route sans remplacer le document. La garde rend les deux cas idempotents.

Utilisez l’URL d’API affichée par votre projet ChattyBox plutôt que de copier un déploiement d’exemple. Consultez la référence d’installation du widget pour connaître les attributs actuels, ainsi que le guide produit Docusaurus pour des conseils sur la sélection des sources et l’évaluation.

2. Garder le chargeur monté

Ne placez pas ce script dans une page de documentation individuelle ou dans une mise en page que Docusaurus remplace lors de la navigation. Le composant Root personnalisé enveloppe l’application pendant toute sa durée de vie : le widget reste donc disponible lorsque les visiteurs passent d’un guide à une référence.

Si votre site possède déjà src/theme/Root.tsx, fusionnez l’effet dans le composant existant au lieu de remplacer les fournisseurs d’authentification, d’analytics ou autres.

3. Tenir compte de la Content Security Policy

Une politique restrictive doit autoriser :

• https://chattybox.ai dans script-src pour le chargeur du widget.
• L’origine de votre API de chat configurée dans connect-src.
• https://fonts.googleapis.com dans style-src et https://fonts.gstatic.com dans font-src si la police du widget n’est pas déjà disponible.
• Les styles de composant en ligne dans style-src pour la version actuelle du widget.

Partez de votre politique existante et ajoutez uniquement les origines que vous utilisez réellement. Ne remplacez pas une politique restrictive par un caractère générique trop permissif.

4. Reproduire les vérifications de l’intégration

Dans votre projet Docusaurus, ajoutez le wrapper Root ci-dessus et exécutez :

bun install
bun run start

Vérifiez ensuite :

1. Ouvrez deux routes de documentation différentes sans actualiser complètement le navigateur.
2. Exécutez document.querySelectorAll('#chattybox-widget').length après chaque navigation. La valeur doit rester 1.
3. Posez une question à laquelle répond une page indexée et vérifiez que la réponse contient un lien vers cette page.
4. Posez une question non prise en charge et vérifiez que l’assistant utilise une réponse de repli au lieu d’inventer une source.
5. Testez le lanceur dans une fenêtre mobile étroite et vérifiez qu’il ne recouvre ni la navigation ni les contrôles de pagination.

La vérification du nombre de scripts prouve que les duplications sont évitées. Elle ne prouve pas la qualité de la récupération. Utilisez un jeu de questions représentatif et le guide de scraping pour valider la couverture des sources avant le lancement.

Ce qu’il faut surveiller après le lancement

Consignez les questions non résolues, les citations incorrectes, les pages sources obsolètes et les routes où le lanceur masque les contrôles du site. Effectuez de nouveaux tests après les mises à niveau du thème Docusaurus, car les changements de navigation et de mise en page du contenu peuvent affecter le positionnement même lorsque le chargeur reste correct.

Pour une séquence de déploiement plus large, utilisez la check-list d’implémentation du chatbot pour documentation et la check-list de lancement.

Sources

• Référence d’installation du widget ChattyBox
• Documentation du swizzling de Docusaurus
• Guide MDN sur la Content Security Policy