The 2026 State of Docs report is here.
Read the report
PricingLog inSign up

Balise script

Découvrez comment ajouter le widget Docs Embed à n’importe quel site web ou application web à l’aide d’une simple balise script

La méthode d’intégration la plus simple pour intégrer GitBook Assistant à votre site web ou à votre application est un script autonome que vous incluez dans votre HTML. Chaque site de documentation GitBook fournit un script d’intégration prêt à l’emploi qui charge automatiquement le widget et le connecte à votre documentation. Cette page vous explique comment faire.

Aucun SDK, étape de build ou intégration à un framework n’est nécessaire. Il suffit d’inclure le script et le widget apparaît sur votre page.

Commencer

1

Copiez l’URL de votre script d’intégration

Accédez à votre site de documentation dans l’application GitBook, puis allez à l’ Paramètres onglet puis à IA et MCP et copiez l’URL du script d’intégration.

Vous pouvez aussi le construire manuellement :

https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js

Remplacez votre YOUR_DOCS_DOMAIN par le domaine réel de votre site de documentation.

2

Ajoutez le script à votre HTML

Ajoutez la balise suivante dans le HTML de votre page. Placez-la à l’intérieur de <head> ou juste avant </body>.

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>window.GitBook('show');</script>
3

Si votre documentation nécessite une authentification

Si votre documentation est protégée par authentification, le script doit inclure un jeton JWT signé.

Ajoutez-le en tant que paramètre de requête :

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js?jwt_token=YOUR_TOKEN"></script>
4

Vérifiez

Rechargez votre page.

Le widget devrait apparaître dans le coin inférieur droit.

Configurez l’intégration de manière facultative

Vous pouvez personnaliser le widget avant de l’afficher. Appelez configure après avoir chargé le script et avant d’appeler window.GitBook('show').

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
balise
  window.GitBook('configure', {
    button: {
      label: 'Ask',
      icon: 'assistant' // assistant | sparkle | help | book
    },
    trademark: false,
    tabs: ['assistant', 'docs'],
    actions: [
      {
        icon: 'circle-question',
        label: 'Contacter le support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ],
    greeting: {
      title: 'Bienvenue',
      subtitle: 'Comment puis-je vous aider ?'
    },
    suggestions: [
      'Qu’est-ce que GitBook ?',
      'Comment puis-je commencer ?'
    ]
  });

  window.GitBook('show');
</script>

Avec cette méthode, vous pouvez personnaliser :

  • Le libellé et l’icône du bouton

  • Les onglets visibles dans le widget

  • Les boutons d’action personnalisés

  • Le titre et le sous-titre de bienvenue

  • Les suggestions affichées aux utilisateurs.

Contrôler la visibilité du widget

Vous pouvez contrôler la visibilité et l’état à l’exécution via l’API.

balise
  // Rendre le widget visible
  window.GitBook('show');

  // Supprimer le widget de la page
  window.GitBook('hide');

  // Ouvrir le panneau du widget
  window.GitBook('open');

  // Fermer le panneau du widget
  window.GitBook('close');

  // Basculer entre ouvert et fermé
  window.GitBook('toggle');
</script>

C’est utile lorsque vous souhaitez connecter le widget à vos propres déclencheurs d’interface utilisateur.

Naviguer et interagir par programmation

Vous pouvez piloter le widget depuis votre code pour naviguer, changer d’onglet ou envoyer des messages.

balise
  // Ouvrir une page spécifique de la documentation dans le widget
  window.GitBook('navigateToPage', '/getting-started');

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

  // Envoyer un message utilisateur à l’assistant
  window.GitBook('postUserMessage', 'Comment puis-je commencer ?');

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

Les utilisations courantes de cette fonctionnalité incluent :

  • Ajouter un lien profond vers une page de documentation depuis votre application

  • Pré-remplir une question

  • Réinitialiser la conversation entre les parcours

Charger le script d’intégration dynamiquement

Si vous souhaitez charger le widget uniquement de manière conditionnelle, ou si vous devez ajouter un jeton d’authentification à l’exécution, injectez le script par programmation.

balise
  function loadGitBookEmbed() {
    var token = "" // Remplissez-le avec votre jeton JWT si votre site nécessite une authentification
    var script = document.createElement('script');
    script.src = 'https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js'
      + token ? '?jwt_token=' + encodeURIComponent(token) : ';
    script.async = true;
    script.onload = function () {
      window.GitBook('show');
    };
    document.head.appendChild(script);
  }

  loadGitBookEmbed();
</script>

Utilisez ce modèle lorsque le widget ne doit se charger qu’après une action de l’utilisateur ou selon des indicateurs de fonctionnalité

Référence de l’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') - Aller à 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', {...}):

tabs

Remplacer les onglets affichés. Par défaut, la configuration de votre site est utilisée.

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

  • Options:

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

    • ['assistant'] - Afficher uniquement l’onglet assistant

    • ['docs'] - Afficher uniquement l’onglet documentation

actions

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

Remarque: Cela s’appelait auparavant buttons. Utilisez actions .

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

  • Propriétés:

    • icon: string - Nom de l’icône. Tout icône FontAwesome est pris en charge

    • label: string - Texte du libellé du bouton

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

greeting

Message de bienvenue affiché dans l’onglet Assistant.

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

suggestions

Questions suggérées affichées sur l’écran d’accueil de l’Assistant.

  • Tapez: string[]

trademark

Afficher ou masquer la marque GitBook dans l’interface intégrée — y compris le pied de page de l’intégration Docs et l’image de marque de l’Assistant.

  • Tapez: boolean

  • Par défaut: true

  • Exemple:

window.GitBook('configure', {
  trademark: false
});

tools

Outils d’IA personnalisés pour étendre l’Assistant. Voir Création d’outils personnalisés pour plus de détails.

  • Tapez: 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.

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

  • Propriétés:

    • label: 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 l’implémentation par 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é)

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

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

  • Propriétés:

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

    • unsignedClaims: Record<string, unknown> (facultatif) - Réclamations 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 votre documentation, et non l’exemple docs.company.com.

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

  • La documentation authentifiée n’est pas accessible – Si votre documentation nécessite une connexion, vous devez fournir le visitor.token lors de l’initialisation. Voir Utilisation avec une documentation authentifiée.

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

  • Le widget n’est pas visible – Vérifiez les conflits de z-index avec d’autres éléments de votre page. Le widget utilise par défaut un z-index élevé.

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

Mis à jour

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