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 façon la plus simple d'ajouter Docs Embed à votre site web ou 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 faire.

Aucun SDK, étape de compilation ou intégration de 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, puis allez dans le Paramètres onglet puis vers 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.

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 protégée par une 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>

Vérifiez

Rechargez votre page.

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

Configurer 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: 'Poser une question',
      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: 'Copilote d'assistance',
    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
Boutons d'action personnalisés
Le titre et le sous-titre de bienvenue
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 les onglets, répertoriez chaque onglet que vous souhaitez conserver.

Définir 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 des préférences du navigateur.

Si vous souhaitez imposer 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 telles que 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');

  // Retirer 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>

Ceci 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');

  // Basculer vers l'onglet assistant
  window.GitBook('navigateToAssistant');

  // Envoyer un message utilisateur à l'assistant
  window.GitBook('postUserMessage', 'How do I get started?');

  // Effacer l'historique de discussion 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 flux

Charger le script d'intégration dynamiquement

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

<script>
  function loadGitBookEmbed() {
    var token = "" // Renseignez-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 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

CSS de l'iframe

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') - Accéder à l'onglet de l'assistant

Chat

GitBook('postUserMessage', message: string) - Publier un message dans le 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', {...}):

`les onglets`

Remplacez les onglets affichés.

La recherche est activée par défaut. Si vous définissez les onglets, l’embed n’affiche que les onglets que vous listez.

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 de 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:
- icône: string - Nom de l'icône. Tout icône FontAwesome est pris en charge
- libellé: 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 }

`assistantName`

Remplacez le nom de l’assistant affiché dans l’interface.

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

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

`closeButton`

Affiche un bouton de fermeture dans l’Assistant.

Tapez: booléen
Exemple:

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

`suggestions`

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

Tapez: string[]

`marque déposée`

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

Tapez: booléen
Par défaut: vrai
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:
- libellé: string - Le texte affiché sur le bouton
- icône: 'assistant' | 'sparkle' | 'help' | 'book' - L'icône affichée sur le bouton
  - assistant - Icône Assistant
  - sparkle - Icône Étincelle
  - help - Icône d'aide/de question
  - book - Icône Livre

Exemple :

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

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

`frameOptions`

Certaines options sont définies sur le cadre plutôt qu'en tant que configuration. Transmettez-les dans frameOptions lors de l'appel de GitBook('init', options, frameOptions).

`colorScheme`

Remplacez le jeu 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 du parent de la page ou de la préférence 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 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) - Revendications non signées pour les expressions dynamiques

Pièges courants

L'URL du script est incorrecte – Assurez-vous d'utiliser la véritable URL de votre documentation, et non l'exemple docs.company.com.
Appeler GitBook avant le chargement du script – Enveloppez les appels API dans script.onload ou placez-les après la balise de script.
Documentation authentifiée inaccessible – 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 de scripts et d'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 il y a 28 jours

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

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

Configurer l'intégration en option

Définir le schéma de couleurs

Contrôle de la visibilité du widget

Naviguer et interagir par programmation

Charger le script d'intégration dynamiquement

Référence de l’API

Initialisation

CSS de l'iframe

Navigation

Chat

Configuration

Options de configuration

`GitBook('configure')`

`les onglets`

`actions`

`greeting`

`assistantName`

`closeButton`

`suggestions`

`marque déposée`

`tools`

`bouton`

`frameOptions`

`colorScheme`

`visitor` (Accès authentifié)

Piè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

Configurer l'intégration en option

Définir le schéma de couleurs

Contrôle de la visibilité du widget

Naviguer et interagir par programmation

Charger le script d'intégration dynamiquement

Référence de l’API

Initialisation

CSS de l'iframe

Navigation

Chat

Configuration

Options de configuration

GitBook('configure')

les onglets

actions

greeting

assistantName

closeButton

suggestions

marque déposée

tools

bouton

frameOptions

colorScheme

visitor (Accès authentifié)

Pièges courants

`GitBook('configure')`

`les onglets`

`actions`

`greeting`

`assistantName`

`closeButton`

`suggestions`

`marque déposée`

`tools`

`bouton`

`frameOptions`

`colorScheme`

`visitor` (Accès authentifié)