The 2026 State of Docs survey is live 📝 Whether you write, edit, or just rely on docs, we want to hear from you!
Take the survey
PricingLog inSign up

Balise script

Ajoutez Docs Embed à n'importe quel site web avec une simple balise script

La manière la plus rapide d'ajouter Docs Embed à votre site Web ou application est de l'ajouter via une balise de script « autonome ». Chaque site de documentation dans GitBook inclut un script prêt à l'emploi pour intégrer vos docs en tant que widget.

Étapes

1

Obtenez l'URL du script d'intégration

Allez dans le Paramètres → IA & MCP onglet et copiez l'URL du script, ou utilisez le script à https://docs.company.com/~gitbook/embed/script.js (remplacez docs.company.com par l'URL réelle de votre site de documentation).

2

Ajoutez la balise script à votre HTML

Placez ce code dans votre HTML <head> ou avant la fermeture de </body> balise :

<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
<script>
  // Initialiser avec un accès authentifié (optionnel)
  window.GitBook('init', 
    { siteURL: 'https://docs.company.com' },
    { visitor: { token: 'your-jwt-token' } }
  );
  window.GitBook('show');
</script>
3

Remplacez l'URL des docs

Mettez à jour docs.company.com avec l'URL réelle de votre site de documentation.

4

Testez le widget

Chargez votre page. Le widget intégré devrait apparaître dans le coin inférieur droit.

5

Configurer éventuellement l'intégration

Ajoutez des options de personnalisation avant d'appeler show():

<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
<script>
  window.GitBook('init', { siteURL: 'https://docs.company.com' });
  
  window.GitBook('configure', {
    button: {
      label: 'Ask',
      icon: 'assistant' // 'assistant' | 'sparkle' | 'help' | 'book'
    },
    tabs: ['assistant', 'docs'],
    actions: [
      {
        icon: 'circle-question',
        label: 'Contact Support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ],
    greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
    suggestions: ['What is GitBook?', 'How do I get started?']
  });
  
  window.GitBook('show');
</script>
6

Contrôler la visibilité du widget

Utilisez l'API pour afficher, masquer, ouvrir ou fermer l'intégration :

<script>
  // Afficher le widget
  window.GitBook("show");

  // Masquer le widget
  window.GitBook("hide");

  // Ouvrir la fenêtre d'intégration
  window.GitBook("open");

  // Fermer la fenêtre d'intégration
  window.GitBook("close");

  // Basculer la fenêtre d'intégration
  window.GitBook("toggle");
</script>
7

Naviguer et interagir par programmation

Utilisez l'API pour naviguer vers des pages, changer d'onglet ou envoyer des messages :

<script>
  // Naviguer vers une page spécifique dans l'onglet docs
  window.GitBook('navigateToPage', '/getting-started');

  // Passer à l'onglet assistant
  window.GitBook('navigateToAssistant');

  // Envoyer un message au chat
  window.GitBook('postUserMessage', 'How do I get started?');

  // Effacer l'historique du chat
  window.GitBook('clearChat');
</script>
8

Charger dynamiquement (optionnel)

Pour des docs authentifiés ou un chargement conditionnel, injectez le script à l'exécution :

<script>
  function loadGitBookEmbed() {
    var script = document.createElement("script");
    script.src = "https://docs.company.com/~gitbook/embed/script.js";
    script.async = true;
    script.onload = function () {
      window.GitBook('init', { siteURL: 'https://docs.company.com' });
      window.GitBook("show");
    };
    document.head.appendChild(script);
  }

  // Charger quand prêt
  loadGitBookEmbed();
</script>
9

Vérifiez la configuration

Ouvrez la console de votre navigateur et tapez window.GitBook pour confirmer que l'API est disponible.

Référence API

Initialisation

  • GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} }) - Initialiser le widget avec l'URL du site et un accès authentifié optionnel

Contrôle du widget

  • GitBook('show') - Afficher le bouton du widget

  • GitBook('hide') - Masquer le bouton du widget

  • GitBook('open') - Ouvrir la fenêtre du widget

  • GitBook('close') - Fermer la fenêtre du widget

  • GitBook('toggle') - Basculer la fenêtre du widget

Navigation

  • GitBook('navigateToPage', path: string) - Naviguer vers une page spécifique dans l'onglet docs

  • GitBook('navigateToAssistant') - Naviguer vers l'onglet assistant

Chat

  • GitBook('postUserMessage', message: string) - Envoyer un message au chat

  • GitBook('clearChat') - Effacer l'historique du chat

Configuration

  • GitBook('configure', settings: {...}) - Configurer les paramètres du widget (voir la section Configuration ci-dessous)

  • GitBook('unload') - Supprimer complètement le widget de la page

Options de configuration

Les options de configuration sont disponibles via GitBook('configure', {...}):

onglets

Remplacez les onglets affichés. Par défaut, ils correspondent à la configuration de votre site.

  • Type: ('assistant' | 'docs')[]

  • Options:

    • ['assistant', 'docs'] - Afficher les deux onglets

    • ['assistant'] - N'afficher que l'onglet assistant

    • ['docs'] - N'afficher que l'onglet docs

actions

Boutons d'action personnalisés rendus dans la barre latérale à côté des onglets. Chaque bouton d'action déclenche un rappel lorsqu'il est cliqué.

Remarque: Ceci était précédemment nommé buttons. Utilisez actions à la place.

  • Type: Array<{ icon: string, label: string, onClick: () => void }>

  • Propriétés:

    • icon: string - Nom de l'icône. Toute icône FontAwesome est prise en charge

    • libellé: string - Texte du label du bouton

    • onClick: () => void | Promise<void> - Fonction de rappel lors du clic

greeting

Message de bienvenue affiché dans l'onglet Assistant.

  • Type: { title: string, subtitle: string }

suggestions

Questions suggérées affichées dans l'écran de bienvenue de l'Assistant.

  • Type: string[]

tools

Outils IA personnalisés pour étendre l'Assistant. Voir Création d'outils personnalisés pour les détails.

  • Type: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

bouton

Configurez le bouton du widget qui lance l'intégration (script autonome uniquement). Cela vous permet de personnaliser le libellé et l'icône du bouton qui apparaît dans le coin inférieur droit de votre page.

  • Type: { label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }

  • Propriétés:

    • libellé: string - Le texte affiché sur le bouton

    • icon: 'assistant' | 'sparkle' | 'help' | 'book' - L'icône affichée sur le bouton

      • assistant - Icône Assistant

      • sparkle - Icône Étincelle

      • help - Icône Aide/question

      • book - Icône Livre

Exemple :

window.GitBook('configure', {
  button: {
    label: 'Ask',
    icon: 'assistant'
  }
});

Remarque : Cette option n'est disponible que lors de l'utilisation de la balise de script autonome. Pour les implémentations React ou Node.js, vous devrez créer votre propre bouton pour déclencher l'intégration.

visitor (Accès authentifié)

À passer lors de l'initialisation avec GitBook('init', options, frameOptions). Utilisé pour Contenu adaptatif et Accès authentifié.

  • Type: { token?: string, unsignedClaims?: Record<string, unknown> }

  • Propriétés:

    • token: string (optionnel) - Jeton JWT signé

    • unsignedClaims: Record<string, unknown> (optionnel) - Reclamations non signées pour les expressions dynamiques

Pièges courants

  • L'URL du script est incorrecte – Assurez-vous d'utiliser l'URL réelle de vos docs, et non l'exemple docs.company.com.

  • Appel de GitBook avant le chargement du script – Enveloppez les appels API dans script.onload ou placez-les après la balise script.

  • Docs authentifiées non accessibles – Si vos docs nécessitent une connexion, vous devez fournir le visitor.token lors de l'initialisation. Voir Utilisation avec des docs authentifiées.

  • Erreurs CORS ou CSP – Assurez-vous que la politique de sécurité de contenu (CSP) de votre site autorise le chargement de scripts et d'iframes depuis votre domaine GitBook.

  • Widget non visible – Vérifiez les conflits de z-index avec d'autres éléments de votre page. Le widget utilise un z-index élevé par défaut.

  • Oubli d'initialisation – Assurez-vous d'appeler GitBook('init', { siteURL: '...' }) avant d'utiliser d'autres méthodes.

Mis à jour

Ce contenu vous a-t-il été utile ?