Passer au contenu principal
ChattyBoxCommencer gratuitement

Chatbot IA avec citations pour Docusaurus 3

· 4 minutes de lecture
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

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 protège cette insertion précise contre les remontages de React en développement et les changements de route côté client. Il ne détecte pas un autre chargeur dont l’identifiant est différent ou absent ; utilisez une seule intégration par page.

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.
  • Pour le chargeur du code source actuel, https://fonts.googleapis.com dans style-src et https://fonts.gstatic.com dans font-src lorsqu’il injecte la feuille de style Inter. Un lien correspondant vers une feuille de style Google Fonts empêche cette injection ; la simple disponibilité de la police ne suffit pas. Vérifiez le comportement du chargeur déployé.
  • L’origine de toute image d’icône personnalisée configurée dans img-src.
  • 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 des questions non prises en charge et évaluez si l’assistant utilise une réponse de repli au lieu d’inventer une source ; répétez le test avec des cas représentatifs sans supposer qu’il s’abstiendra dans chaque réponse.
  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 ne compte que les scripts portant cet identifiant ; un autre chargeur sans identifiant ou avec un identifiant différent peut toujours exister. Vérifiez aussi toutes les intégrations et le widget affiché. Ce comptage 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​