Ajouter un chatbot IA avec citations à MkDocs

Les thèmes MkDocs exposent différents répertoires de surcharge, et Material peut naviguer entre les pages sans rechargement complet. Une intégration durable doit préserver les scripts existants du thème, charger le widget une seule fois et coexister avec la recherche et la navigation sur mobile.

Auteur et relecteur technique : Michael Fisher, mainteneur de ChattyBox. Publié et vérifié techniquement le 10 juillet 2026. Le protocole de vérification ci-dessous est un tutoriel d’implémentation ; aucun résultat de trafic, de déflexion des demandes ou de précision des réponses n’est revendiqué.

1. Choisir le bon répertoire de surcharge

Pour Material for MkDocs, pointez custom_dir vers un répertoire overrides :

site_name: My documentation
theme:
  name: material
  custom_dir: overrides
  features:
    - navigation.instant

Pour le thème intégré, utilisez un répertoire de thème personnalisé distinct :

site_name: My documentation
theme:
  name: mkdocs
  custom_dir: custom_theme

Le fait de conserver les variantes séparées indique clairement quel modèle de base en amont est étendu.

2. Étendre le bloc scripts

Créez overrides/main.html pour Material ou custom_theme/main.html pour le thème intégré :

{% extends "base.html" %}

{% block scripts %}
  {{ super() }}
  <script
    id="chattybox-widget"
    src="https://chattybox.ai/widget.js"
    async
    data-api-key="YOUR_API_KEY"
    data-api-url="YOUR_CHAT_API_URL"
    data-chattybox-widget="true"
  ></script>
{% endblock %}

{{ super() }} préserve les scripts fournis par le thème, notamment les comportements de navigation et de recherche. Son omission peut donner l’impression que le widget fonctionne tout en cassant silencieusement l’interface de documentation. L’ID stable fournit également une assertion directe contre les doublons du chargeur.

Utilisez les valeurs propres à votre projet indiquées dans la référence d’installation du widget. Le guide du chatbot IA pour MkDocs couvre le périmètre des sources, le comportement du crawl et les questions à évaluer avant la publication.

3. Construire les deux variantes

Depuis votre projet MkDocs :

python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

cd material
mkdocs build --strict

cd ../vanilla
mkdocs build --strict

--strict transforme les avertissements en échecs, ce qui permet de détecter les problèmes de navigation et de configuration avant d’évaluer le widget.

4. Exécuter les vérifications dans le navigateur

Servez chaque variante et vérifiez les points suivants :

1. La recherche intégrée s’ouvre toujours et renvoie le résultat de documentation attendu.
2. La navigation instantanée de Material change de route sans dupliquer le chargeur du widget.
3. document.querySelectorAll('#chattybox-widget').length reste égal à 1 après plusieurs changements de route.
4. Dans une fenêtre de 390 px, le lanceur ne recouvre ni la recherche, ni la navigation, ni les contrôles précédent/suivant.
5. Une question prise en charge cite la page attendue, tandis qu’une question non prise en charge produit une réponse de repli prudente.

Les quatre premières vérifications valident le comportement de l’intégration. La cinquième dépend des pages que vous indexez et nécessite un jeu d’évaluation représentatif ; suivez le guide de scraping et la check-list de lancement plutôt que de considérer le chargement réussi du script comme une preuve de la qualité des réponses.

5. Préserver une CSP restrictive

Autorisez l’hôte du widget dans script-src, l’origine de l’API configurée dans connect-src et les origines des polices dans style-src et font-src lorsque nécessaire. Le widget actuel injecte des styles de composant ; une politique par ailleurs stricte nécessite donc aussi une stratégie explicite pour les styles en ligne. Évitez les listes de sources génériques.

Liste de contrôle de maintenance

Reconstruisez les deux variantes du thème après les mises à niveau de MkDocs ou de Material, car les noms des blocs de modèles en amont peuvent changer. Conservez l’ID du script, préservez super() et relancez les vérifications de recherche, de navigation instantanée, de chevauchement sur mobile et de citation des sources.

Pour planifier le déploiement de bout en bout, utilisez la check-list d’implémentation du chatbot pour documentation.

Sources

• Référence d’installation du widget ChattyBox
• Personnalisation des thèmes MkDocs
• Personnalisation de Material for MkDocs
• Guide MDN sur la Content Security Policy