Balise script

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

La façon la plus simple d’ajouter Docs Embed à votre site web ou à votre application est d’utiliser 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 procéder.

Aucun SDK, étape de build ou intégration à un framework n’est requis. Incluez simplement le script et le widget apparaît sur votre page.

Commencer

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

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

Vous pouvez aussi le créer manuellement :

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

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

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>

Si votre documentation nécessite une authentification

Si votre documentation est derrière l’authentification, le script doit inclure un jeton JWT signé.

Ajoutez-le comme paramètre de requête :

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

Vérifiez

Rechargez votre page.

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

Configurez l’intégration en option

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

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>
  window.GitBook('configure', {
    button: {
      label: 'Demander',
      icon: 'assistant' // assistant | sparkle | help | book
    },
    trademark: false,
    tabs: ['assistant', 'search', '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 ?'
    },
    assistantName: 'Support Copilot',
    closeButton: true,
    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 d’accueil
Le nom de l’assistant affiché dans l’interface
Le bouton de fermeture dans l’Assistant
Les invites suggérées affichées aux utilisateurs.

La recherche est activée par défaut. Si vous définissez onglets, listez chaque onglet que vous souhaitez conserver.

Définissez le schéma de couleurs

Par défaut, l’intégration suit le CSS de l’iframe color-scheme. Cela lui permet d’hériter automatiquement du thème de votre application ou de la préférence du navigateur.

Si vous souhaitez forcer un mode, initialisez l’intégration et transmettez colorScheme dans frameOptions:

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>
  window.GitBook(
    'init',
    { siteURL: 'https://YOUR_DOCS_DOMAIN' },
    { colorScheme: 'dark' }
  );

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

Utilisez ce modèle lorsque vous avez besoin d’options au niveau du cadre, comme colorScheme ou visitor.

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

<script>
  // 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.

Naviguer et interagir par programmation

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

<script>
  // Ouvrir une page de documentation spécifique 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 de chat actuel
  window.GitBook('clearChat');
</script>

Les utilisations typiques 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 étapes

Charger le script d’intégration de façon dynamique

Si vous ne souhaitez charger le widget que conditionnellement, ou si vous devez attacher un jeton d’authentification à l’exécution, injectez le script par programmation.

<script>
  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 doit se charger uniquement 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?: {...}, colorScheme?: 'light' | 'dark' }) - Initialiser le widget avec l’URL du site et des options de cadre facultatives

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

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

`GitBook('configure')`

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

`onglets`

Remplace les onglets affichés.

La recherche est activée par défaut. Si vous définissez onglets, l’embed n’affiche que les onglets que vous avez सूचीés.

Tapez: ('assistant' | 'search' | 'docs')[]
Options:
- ['assistant', 'search', 'docs'] - Afficher tous les onglets
- ['search', 'docs'] - Afficher uniquement la recherche et la documentation
- ['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: Ceci s’appelait auparavant buttons. Utilisez actions à la place.

Tapez: 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 libellé du bouton
- onClick: () => void | Promise<void> - Fonction de rappel lors du clic

`greeting`

Message de bienvenue affiché dans l’onglet Assistant.

Tapez: { title: string, subtitle: string }

`assistantName`

Remplace le nom de l’assistant affiché dans l’interface utilisateur.

Tapez: string
Longueur max: 32 caractères
Exemple:

window.GitBook('configure', {
  assistantName: 'Support Copilot'
});

`closeButton`

Affiche un bouton de fermeture dans l’Assistant.

Tapez: boolean
Exemple:

window.GitBook('configure', {
  closeButton: true
});

`suggestions`

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

Tapez: string[]

`trademark`

Afficher ou masquer la marque GitBook dans l’interface d’intégration — y compris le pied de page de Docs Embed et l’identité visuelle de l’Assistant.

Tapez: boolean
Par défaut: true
Exemple:

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

`tools`

Outils 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:
- libellé: string - Le texte affiché sur le bouton
- icon: 'assistant' | 'sparkle' | 'help' | 'book' - L’icône affichée sur le bouton
  - assistant - Icône d’assistant
  - sparkle - Icône d’étincelle
  - help - Icône d’aide / question
  - book - Icône de livre

Exemple :

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

Remarque : Cette option est disponible uniquement lorsque vous utilisez 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.

`frameOptions`

Certaines options se définissent sur le cadre plutôt que dans la configuration. Transmettez-les dans frameOptions lors de l’appel GitBook('init', options, frameOptions).

`colorScheme`

Remplace le schéma de couleurs de l’intégration.

Lorsqu’elle est omise, l’intégration suit le CSS de l’iframe color-scheme , ce qui lui permet d’hériter de la préférence de la page parente ou du navigateur.

Tapez: 'light' | 'dark'
Exemple:

window.GitBook(
  'init',
  { siteURL: 'https://docs.company.com' },
  { colorScheme: 'dark' }
);

`visitor` (Accès authentifié)

À transmettre lors de l’initialisation avec GitBook('init', options, frameOptions). Utilisé pour Adaptive Content 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) - Revendications 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 script.
Documentation authentifiée inaccessible – Si votre documentation nécessite une connexion, vous devez fournir 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 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 par défaut un z-index élevé.
Oublier d’initialiser – Assurez-vous d’appeler GitBook('init', { siteURL: '...' }) avant d’utiliser les autres méthodes.

Mis à jour il y a 1 mois

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

Bonne nuit

Balise script

Commencer

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

Ajoutez le script à votre HTML

Si votre documentation nécessite une authentification

Vérifiez

Configurez l’intégration en option

Définissez le schéma de couleurs

Contrôler la visibilité du widget

Naviguer et interagir par programmation

Charger le script d’intégration de façon dynamique

Référence de l’API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`GitBook('configure')`

`onglets`

`actions`

`greeting`

`assistantName`

`closeButton`

`suggestions`

`trademark`

`tools`

`bouton`

`frameOptions`

`colorScheme`

`visitor` (Accès authentifié)

Pièges courants

Bonne nuit

hashtagCommencer

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

hashtagAjoutez le script à votre HTML

hashtagSi votre documentation nécessite une authentification

hashtagVérifiez

hashtagConfigurez l’intégration en option

hashtagDéfinissez le schéma de couleurs

hashtagContrôler la visibilité du widget

hashtagNaviguer et interagir par programmation

hashtagCharger le script d’intégration de façon dynamique

hashtagRéférence de l’API

hashtagInitialisation

hashtagContrôle du widget

hashtagNavigation

hashtagChat

hashtagConfiguration

hashtagOptions de configuration

hashtagGitBook('configure')

hashtagonglets

hashtagactions

hashtaggreeting

hashtagassistantName

hashtagcloseButton

hashtagsuggestions

hashtagtrademark

hashtagtools

hashtagbouton

hashtagframeOptions

hashtagcolorScheme

hashtagvisitor (Accès authentifié)

hashtagPièges courants

Commencer

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

Ajoutez le script à votre HTML

Si votre documentation nécessite une authentification

Vérifiez

Configurez l’intégration en option

Définissez le schéma de couleurs

Contrôler la visibilité du widget

Naviguer et interagir par programmation

Charger le script d’intégration de façon dynamique

Référence de l’API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`GitBook('configure')`

`onglets`

`actions`

`greeting`

`assistantName`

`closeButton`

`suggestions`

`trademark`

`tools`

`bouton`

`frameOptions`

`colorScheme`

`visitor` (Accès authentifié)

Pièges courants