Comment ajouter le chatbot IA Asyntai à Docusaurus

Guide étape par étape pour les sites de documentation Docusaurus

Plateforme :

Étape 1 : Obtenir votre code d'intégration

Tout d'abord, rendez-vous sur votre Tableau de bord Asyntai et faites défiler jusqu'à la section « Code d'intégration ». Copiez votre code d'intégration unique qui ressemblera à ceci :

<script async src="https://asyntai.com/static/js/chat-widget.js" data-asyntai-id="YOUR_WIDGET_ID"></script>

Note : Le code ci-dessus n'est qu'un exemple. Vous devez copier votre propre code d'intégration depuis votre Tableau de bord car il contient votre identifiant de widget personnel.

Étape 2 : Ajouter le script à docusaurus.config.js (recommandé)

La meilleure façon d'ajouter le chatbot à toutes les pages de votre site Docusaurus est via le fichier de configuration :

Ouvrez votre projet Docusaurus dans votre éditeur de code
Localisez et ouvrez le fichier docusaurus.config.js à la racine de votre projet
Trouvez l'objet const config = { }
Ajoutez ou mettez à jour le champ scripts avec votre widget Asyntai :

const config = {
  // ... other config options

  scripts: [
    // Other scripts if any
    {
      src: 'https://asyntai.com/static/js/chat-widget.js',
      'data-asyntai-id': 'YOUR_WIDGET_ID',
      async: true,
    },
  ],

  // ... rest of config
};

Enregistrez le fichier docusaurus.config.js
Reconstruisez votre site en exécutant npm run build ou yarn build
Redémarrez le serveur de développement si vous travaillez en local

Astuce : Le champ scripts accepte un tableau de sources JavaScript. La balise script sera insérée automatiquement dans le head HTML de chaque page. C'est la méthode la plus propre et la plus maintenable pour les sites Docusaurus.

Méthode alternative 1 : Format chaîne (syntaxe plus simple)

Si vous préférez une approche plus simple, vous pouvez utiliser le format chaîne dans le tableau de scripts :

const config = {
  scripts: [
    'https://asyntai.com/static/js/chat-widget.js',
  ],
};

Note : Lorsque vous utilisez le format chaîne de caractères, vous devrez modifier l'URL du script pour inclure votre identifiant de widget en tant que paramètre de requête, ou utiliser le format objet présenté à l'étape 2 qui vous permet de définir directement l'attribut data-asyntai-id.

Méthode alternative 2 : Balises d'en-tête personnalisées

Vous pouvez également ajouter le script en utilisant le champ headTags dans docusaurus.config.js :

const config = {
  headTags: [
    {
      tagName: 'script',
      attributes: {
        src: 'https://asyntai.com/static/js/chat-widget.js',
        'data-asyntai-id': 'YOUR_WIDGET_ID',
        async: true,
      },
    },
  ],
};

Astuce : Le champ headTags offre plus de contrôle sur les balises HTML exactes insérées dans la section <head>. Cette méthode est fonctionnellement équivalente à l'utilisation du champ scripts.

Méthode alternative 3 : Template HTML personnalisé (avancé)

Pour les utilisateurs avancés qui ont besoin d'un contrôle complet sur le template HTML :

Créez un nouveau répertoire : src/theme (s'il n'existe pas déjà)
Créez un fichier : src/theme/Root.js
Ajoutez le code suivant pour injecter le script dynamiquement :

import React, { useEffect } from 'react';

export default function Root({children}) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://asyntai.com/static/js/chat-widget.js';
    script.setAttribute('data-asyntai-id', 'YOUR_WIDGET_ID');
    script.async = true;
    document.head.appendChild(script);

    return () => {
      // Cleanup when component unmounts
      document.head.removeChild(script);
    };
  }, []);

  return <>{children}</>;
}

Enregistrez le fichier et reconstruisez votre site

Important : Le composant Root.js englobe l'ensemble de votre application. Cette méthode avancée ne doit être utilisée que si vous avez besoin d'une logique JavaScript personnalisée ou si vous avez des exigences spécifiques qui ne peuvent pas être satisfaites par l'approche via le fichier de configuration.

Méthode alternative 4 : Swizzle du composant Footer

Vous pouvez personnaliser le pied de page pour inclure le script :

Exécutez la commande swizzle : npm run swizzle @docusaurus/theme-classic Footer -- --eject
Cela crée une copie du composant Footer dans src/theme/Footer/
Modifiez le composant Footer pour inclure votre balise script
Ajoutez le script avant la balise fermante du pied de page
Enregistrez et reconstruisez votre site

Note : Le swizzling vous donne un contrôle total sur les composants Docusaurus, mais cela signifie que vous devrez maintenir ce composant vous-même. Les mises à jour de Docusaurus ne mettront pas automatiquement à jour les composants swizzlés.

Étape 3 : Compiler et déployer

Après avoir ajouté le code, compilez et déployez votre site Docusaurus :

# Build the site
npm run build

# Or with Yarn
yarn build

# Deploy to your hosting platform
# (Vercel, Netlify, GitHub Pages, etc.)

Astuce : Pendant le développement, exécutez npm start ou yarn start pour prévisualiser vos modifications en local. Le chatbot devrait apparaître dans le coin inférieur droit sur toutes les pages.

Étape 4 : Vérifier l'installation

Après avoir déployé vos modifications, ouvrez votre site de documentation dans un nouvel onglet de navigateur. Vous devriez voir le bouton du widget de chat dans le coin inférieur droit. Cliquez dessus pour vérifier qu'il s'ouvre et fonctionne correctement.

Vous ne voyez pas le widget ? Assurez-vous d'avoir reconstruit votre site après avoir effectué les modifications. Vérifiez que vous avez remplacé YOUR_WIDGET_ID par votre identifiant de widget réel depuis le Tableau de bord. Videz le cache de votre navigateur ou consultez le site en mode navigation privée. Ouvrez la console du navigateur (F12) pour vérifier s'il y a des erreurs JavaScript.

Documentation