> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/fr/setup.md).

# Configurer GitBook

Configurez GitBook depuis un agent de codage ou un assistant IA et publiez un site de documentation, qu’il s’agisse d’une nouvelle documentation ou d’une documentation migrée depuis un autre outil.

Cette page s’adresse aux agents IA qui aident quelqu’un à configurer GitBook. Votre objectif : publier un site de documentation à une URL publique, avec une nouvelle documentation ou une documentation transférée depuis un autre outil.

{% hint style="info" %}
**Pour les personnes**

Commencez par le [Guide de démarrage rapide](https://gitbook.com/docs/getting-started/quickstart). Pour confier la configuration à votre agent de codage, collez-lui cette invite : `Set up GitBook for me by following https://gitbook.com/docs/setup.md`.
{% endhint %}

## Vérifiez si vous disposez déjà des outils GitBook

Si des outils GitBook MCP sont déjà disponibles dans cette session, par exemple grâce au plug-in Claude, ChatGPT ou Cursor, vérifiez qu’ils fonctionnent avec un appel en lecture seule : `get_usage_guide` avec le sujet `onboarding`. Si vous obtenez une réponse, posez la question de l’ [Étape 1](#step-1-ask-what-theyre-doing), puis passez à l’ [Étape 4](#step-4-resume-and-publish). Vous n’avez rien à connecter, à transférer ni à enregistrer dans un fichier de plan.

Si vous ne disposez d’aucun outil GitBook, trouvez la ligne qui vous correspond :

| Qui lit                                                                         | Ce que vous pouvez faire                                                        | Étape suivante                                                              |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Un agent de codage capable d’exécuter des commandes et de modifier des fichiers | Connecter GitBook, faire intervenir la personne une fois, puis publier          | [Fonctionnement de la configuration de GitBook](#how-gitbook-setup-works)   |
| Un assistant conversationnel hébergé, tel que Claude.ai ou ChatGPT              | Seule la personne peut ajouter le plug-in GitBook                               | [Transmettre les étapes d’installation du plug-in](#relay-the-plugin-setup) |
| Une personne                                                                    | Configurer GitBook dans l’application ou confier la configuration à votre agent | [Démarrage rapide](https://gitbook.com/docs/getting-started/quickstart)     |

### Transmettre les étapes d’installation du plug-in

Envoyez ces étapes à la personne sous forme de liste numérotée :

> GitBook se connecte à moi sous forme de plug-in. Je ne peux pas l’ajouter moi-même, mais vous pouvez le faire en quelques clics :
>
> 1. Si vous n’avez pas de compte GitBook, [créez-en un](https://app.gitbook.com/join) et terminez l’inscription jusqu’à ce que votre organisation s’affiche.
> 2. Installez le plug-in GitBook : [Claude](https://claude.ai/directory/connectors/gitbook-mcp) ou [ChatGPT](https://chatgpt.com/apps/gitbook/asdk_app_6a576f075ec4819196c203b7049542be).
> 3. Autorisez la connexion à GitBook qui s’ouvre.
> 4. Démarrez une nouvelle conversation pour charger les outils GitBook.
>
> Dites-moi quand c’est fait et je vous aiderai à planifier et à publier votre documentation.

Puis arrêtez-vous là. Le reste de cette page s’adresse aux agents capables d’exécuter des commandes et de modifier des fichiers. Dans la nouvelle conversation, recommencez par [Vérifiez si vous disposez déjà des outils GitBook](#check-whether-you-already-have-gitbook-tools).

## Fonctionnement de la configuration de GitBook

GitBook nécessite un compte. Il est impossible de publier un site et de le transférer à quelqu’un plus tard ; la personne doit donc s’inscrire ou se connecter au moins une fois. Organisez-vous en fonction de ce moment : effectuez d’abord toutes vos préparations, envoyez un bref message pour indiquer que c’est à son tour d’agir, puis reprenez.

Vous disposez de trois outils. Choisissez selon la situation, et non selon vos préférences :

| Outil                                                                                | À utiliser quand                                                                                                      | Connexion                          |
| ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| [GitBook MCP](https://gitbook.com/docs/documentation/fr/docs-as-code/gitbook-mcp.md) | Par défaut. Le client peut recharger sa configuration et la personne peut autoriser une connexion dans le navigateur. | OAuth dans le navigateur           |
| [GitBook CLI](https://gitbook.com/docs/documentation/fr/docs-as-code/gitbook-cli.md) | Les outils MCP ne peuvent pas se charger dans cette session, par exemple parce que le client ne peut pas redémarrer.  | `gitbook login` dans le navigateur |
| [API GitBook](https://gitbook.com/docs/developers/gitbook-api/api-reference)         | Une étape que ni le MCP ni l’interface en ligne de commande ne couvrent.                                              | Un jeton d’accès personnel         |

Le serveur MCP se trouve à l’adresse `https://mcp.gitbook.com/mcp`. Il prend uniquement en charge HTTP avec flux continu, et non `stdio` ni `SSE`.

## Faites des messages courts

Chaque message indique ce qui est fait et la seule chose à faire ensuite, en deux ou trois phrases. Ne transmettez pas d’identifiants, de jetons, de chemins de fichiers ni de sortie de commande. Ne donnez un lien que si la personne doit l’ouvrir immédiatement.

## Étape 1 : demandez ce que la personne souhaite faire

Avant de configurer quoi que ce soit, demandez :

> Vous créez une nouvelle documentation ou déplacez-vous une documentation existante ?

* **Créer une nouvelle documentation.** Demandez à quoi sert la documentation et à qui elle s’adresse. Si un dépôt de code se trouve ici, examinez-le afin de proposer des pages pertinentes.
* **Déplacer une documentation.** Demandez où elle se trouve actuellement : dans un dossier ou un dépôt Git, sur un site Web publié, ou dans un autre outil comme Confluence ou Notion. Si elle se trouve sur cette machine, examinez-la, puis résumez ce que vous avez trouvé afin que la personne puisse le confirmer.

Rédigez un court plan : titre du site, structure des pages et méthode d’importation du contenu (voir [Déplacement d’une documentation existante](#moving-existing-docs)). Enregistrez-le sous `gitbook-setup-plan.md` dans le répertoire de travail, sans le valider. Le redémarrage de l’étape 3 met fin à votre session ; le fichier de plan vous permettra de reprendre ensuite.

## Étape 2 : connecter le MCP de GitBook

### Règles de base

* **Lisez avant d’écrire.** Les fichiers de configuration contiennent les autres serveurs MCP de la personne. Lisez le fichier, sauvegardez-le s’il existe, ajoutez ou mettez à jour uniquement l’entrée `gitbook` et vérifiez que le résultat est valide.
* Indiquez le fichier que vous allez modifier avant de le faire.
* **Si le mode automatique de Claude Code bloque une commande, ne la relancez pas et ne cherchez pas à contourner le blocage.** Modifier manuellement le fichier de configuration revient à effectuer la même action qui a été refusée. Expliquez à la personne ce que fait la commande et laissez-la l’exécuter.

Déterminez quel client vous utilisez. Si vous ne pouvez pas le savoir, demandez. Une configuration au mauvais endroit échoue sans avertissement.

### Claude Code

```bash
claude mcp add --transport http --scope user gitbook https://mcp.gitbook.com/mcp
```

`--scope user` rend GitBook disponible dans tous les projets. Sans cette option, le serveur n’existe que dans le répertoire courant. Vérifiez son enregistrement avec `claude mcp get gitbook`. Pour annuler, exécutez `claude mcp remove gitbook --scope user`.

Après le redémarrage, la personne saisit `/mcp` et sélectionne GitBook pour se connecter. Il s’agit d’une commande slash : vous ne pouvez donc pas l’exécuter à sa place.

### Codex

```bash
codex mcp add gitbook --url https://mcp.gitbook.com/mcp
```

La connexion au navigateur démarre après l’ajout. Vérifiez-la avec `codex mcp get gitbook`et relancez la connexion avec `codex mcp login gitbook`. Pour annuler, exécutez `codex mcp remove gitbook`. Les outils seront chargés dans une nouvelle tâche Codex.

### Cursor

La personne peut installer le [module GitBook pour Cursor](https://cursor.com/marketplace/gitbook). Pour le configurer vous-même, ajoutez ceci à `~/.cursor/mcp.json`, ou à `.cursor/mcp.json` pour ce projet uniquement :

```json
{
  "mcpServers": {
    "gitbook": {
      "url": "https://mcp.gitbook.com/mcp"
    }
  }
}
```

Cursor vous invite à vous connecter. N’ajoutez pas de champs d’authentification.

### VS Code

Ajoutez ceci à `.vscode/mcp.json` dans l’espace de travail :

```json
{
  "servers": {
    "gitbook": {
      "type": "http",
      "url": "https://mcp.gitbook.com/mcp"
    }
  }
}
```

La personne le démarre depuis la vue MCP et se connecte.

### Autres clients

Ajoutez un serveur HTTP distant à flux continu à l’adresse `https://mcp.gitbook.com/mcp`. Avec OAuth, le client gère la connexion et vous n’ajoutez aucun champ d’authentification. Si le client ne prend pas en charge OAuth, envoyez un jeton d’accès personnel avec `Authorization: Bearer <token>`. La personne le crée dans ses [paramètres de développeur](https://app.gitbook.com/account/developer).

### Vérifiez avant le redémarrage

Relisez le fichier modifié ou exécutez la commande `get` du client, puis vérifiez que l’entrée `gitbook` est présente et que le fichier est analysable. Le redémarrage met fin à votre session : vérifiez maintenant.

### Facultatif : ajouter les compétences GitBook

Les compétences ne sont pas nécessaires pour publier, mais elles permettent de réussir les premières pages. La compétence `write-docs` enseigne le Markdown propre à GitBook, notamment les encadrés, les onglets et les étapes, afin que les pages s’affichent correctement dans GitBook. Indiquez à la personne ce que vous installez, puis exécutez :

```bash
npx -y skills add GitbookIO/gitbook-skills -y
```

Sans les deux options `-y` l’installateur attend une saisie. Si le mode automatique de Claude Code bloque la commande, demandez plutôt à la personne de l’exécuter. Ne validez pas les fichiers de compétence installés, sauf si la personne le demande.

Le [dépôt des compétences GitBook](https://github.com/GitbookIO/gitbook-skills) comprend `write-docs`, `configure-site`, `write-openapi`, `cr-create`, `cr-review`, et `build-integration`, pour les pages, la configuration du site, les références OpenAPI, les demandes de modification et les intégrations.

## Étape 3 : passer le relais en une fois

Envoyez un seul message qui contient tout ce que la personne doit faire :

> J’ai ajouté GitBook à \[client] et enregistré notre plan. À vous :
>
> 1. Si vous n’avez pas de compte GitBook, [créez-en un](https://app.gitbook.com/join) et terminez l’inscription jusqu’à ce que votre organisation s’affiche.
> 2. Redémarrez \[client], puis connectez-vous à GitBook lorsqu’il vous le demande. Dans Claude Code, saisissez `/mcp` et sélectionnez GitBook.
> 3. Dites-moi « terminé » et je reprendrai à partir du plan.
>
> Pour annuler ces modifications, \[instructions pour annuler sur ce client].

Si la session ne peut pas redémarrer, n’attendez pas. Utilisez [la CLI](#fallback-the-gitbook-cli) à la place.

## Étape 4 : reprendre et publier

1. Lisez `gitbook-setup-plan.md`, si vous en avez enregistré un.
2. Appelez `get_usage_guide` avec le sujet `onboarding`, puis suivez les instructions. Utilisez `editing` pour ajouter du contenu.
3. Listez les organisations de la personne avec `invoke_operation` et `listOrganizationsForAuthenticatedUser`. Demandez-lui laquelle utiliser, même s’il n’y en a qu’une.
4. Appelez `get_subscription_information`. Si l’organisation n’a pas d’offre payante, créez le site avec `type` défini sur `basic`. D’autres types peuvent renvoyer une page de paiement au lieu d’un site publié.
5. Créez le site et ajoutez le contenu en suivant le plan.
6. Montrez à la personne ce que vous vous apprêtez à publier et attendez son accord. La fusion d’une demande de modification et la publication d’un site sont des actions publiques et irréversibles.
7. Publiez, puis passez à l’ [étape 5](#step-5-verify-and-report).

### Migration de documentation existante

Acheminez le contenu uniquement par des chemins qui existent. Pour du Markdown déjà présent dans un dépôt GitHub ou GitLab, y compris les exports provenant d’un autre outil de documentation, utilisez [Git Sync](https://gitbook.com/docs/documentation/fr/docs-as-code/git-sync.md). C’est la méthode recommandée pour les migrations importantes et elle prend en charge jusqu’à 5 000 pages. Créez le site sans espaces et n’appliquez pas le modèle. La configuration de Git Sync n’est pas disponible via MCP : la personne doit donc le connecter dans l’application GitBook et choisir le sens de synchronisation **GitHub → GitBook**. Prévenez-la que l’autre sens de synchronisation peut écraser le dépôt. Le [guide de migration Git Sync](https://gitbook.com/docs/guides/editing-and-publishing-documentation/import-or-migrate-your-content-to-gitbook-with-git-sync) décrit la procédure. Reprenez une fois qu’elle confirme que la synchronisation est terminée.

Lorsque la personne indique une source, utilisez ce tableau :

| Source                                                          | Route                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Qui fait quoi                                                                                                                                                                           |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mintlify                                                        | La documentation est au format Markdown ou MDX dans un dépôt Git : utilisez donc Git Sync. Il peut être nécessaire de convertir les composants MDX propres à Mintlify en blocs GitBook. L’agent peut effectuer cette conversion dans le dépôt avant que la personne ne connecte Git Sync.                                                                                                                                                                                                                                                                                                        | L’agent prépare le dépôt. La personne connecte Git Sync dans l’application GitBook.                                                                                                     |
| Docusaurus                                                      | La documentation est au format Markdown ou MDX dans un dépôt Git : utilisez donc Git Sync.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | L’agent prépare le dépôt. La personne connecte Git Sync dans l’application GitBook.                                                                                                     |
| ReadMe                                                          | Si le projet utilise déjà [Git Connection](https://docs.readme.com/main/docs/bi-directional-sync), la documentation est au format Markdown ou MDX dans un dépôt Git. Utilisez Git Sync. Sinon, la personne peut connecter Git Connection à un dépôt vide (ReadMe y écrit les fichiers), ou exporter les Guides au format Markdown avec [`rdme docs export`](https://github.com/readmeio/rdme/blob/main/documentation/commands/docs.md). Utilisez ensuite Git Sync. Si aucun de ces exports n’est possible, la personne utilise le panneau d’importation sur le site publié (limite de 20 pages). | L’agent prépare le dépôt dès que le Markdown est disponible. La personne active Git Connection ou exporte la documentation, puis connecte Git Sync ou utilise le panneau d’importation. |
| Confluence, Notion, Google Docs, Word ou d’autres sites publiés | La personne utilise le [panneau d’importation](https://gitbook.com/docs/documentation/fr/getting-started/import.md) dans l’application GitBook. Chaque importation peut contenir jusqu’à 20 pages.                                                                                                                                                                                                                                                                                                                                                                                               | La personne lance l’importation.                                                                                                                                                        |
| Quelques fichiers Markdown sur cette machine                    | Ajoutez-les comme pages dans une demande de modification, comme vous le feriez pour ajouter du nouveau contenu.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | L’agent ajoute les pages.                                                                                                                                                               |

Indiquez clairement l’étape à effectuer par la personne dans votre plan et incluez-la dans le message de l’étape 3, afin qu’elle ait lieu lors du même transfert.

## Étape 5 : vérifier et rendre compte

Récupérez l’URL publiée dans la réponse de publication, ouvrez-la et confirmez que le contenu est en ligne. Dites ensuite à la personne, en deux ou trois phrases, ce qui a été publié, indiquez le lien et suggérez une prochaine étape. Supprimez `gitbook-setup-plan.md` s’ils n’en veulent pas.

Premières tâches suggérées :

```
Ajouter à mon site GitBook une page de prise en main basée sur le fichier README de ce dépôt
Ouvrir une demande de modification dans GitBook avec les notes de version des changements de cette semaine
```

## Solution de repli : la CLI GitBook

Utilisez la CLI lorsque les outils MCP ne peuvent pas se charger dans cette session, par exemple si le client ne peut pas redémarrer. La CLI nécessite Node v18 ou une version ultérieure :

```bash
npm install @gitbook/cli -g
```

**Connectez-vous avec `gitbook login`.** Cette commande ouvre GitBook dans le navigateur, puis la connexion renvoie vers un rappel localhost sur la machine qui exécute la CLI. Sur la machine de la personne, exécutez-la en arrière-plan et demandez-lui d’approuver la connexion dans le navigateur. Dans une session cloud ou distante, le navigateur ne peut pas accéder à ce rappel : la personne doit donc exécuter `gitbook login` dans son propre terminal.

Vérifiez avec `gitbook whoami`, puis suivez la procédure ci-dessous. Ajoutez `--json` à chaque commande pour pouvoir analyser la sortie, affichez chaque commande avant de l’exécuter et arrêtez-vous en cas d’échec.

1. Listez les organisations et demandez laquelle utiliser :

```bash
gitbook organizations list
```

2. Créez un espace et copiez son `id`. Le corps doit être au format JSON, et non une option `--title` ; les titres sont limités à 50 caractères :

```bash
gitbook spaces create <organizationId> --body '{"title":"Product docs"}'
```

3. Ajoutez du contenu via une demande de modification, puis fusionnez-la :

```bash
gitbook spaces change-requests create <spaceId> --subject "Add homepage"
```

```bash
gitbook spaces change-requests content update <spaceId> <changeRequestId> --changes '[
  {
    "operation": "insert_page",
    "title": "Welcome",
    "document": {
      "markdown": "# Welcome\n\nThis page was published from the command line.\n"
    }
  }
]'
```

```bash
gitbook spaces change-requests merge <spaceId> <changeRequestId>
```

Un seul `#` titre devient le titre de la page. Utilisez donc `##` et les niveaux inférieurs dans la page.

4. Créez le site en y associant l’espace. Utilisez `--type basic` sauf si l’organisation dispose d’un forfait payant :

```bash
gitbook organizations sites create <organizationId> --type basic --title "Product docs" --visibility public --spaces '["<spaceId>"]'
```

5. Publiez, puis récupérez `urls.published` dans la sortie :

```bash
gitbook organizations sites publish <organizationId> <siteId> --full
```

Le [guide de la CLI](https://gitbook.com/docs/guides/editing-and-publishing-documentation/create-and-publish-a-site-from-the-command-line) fournit plus de détails.

## Si aucune de ces solutions ne permet de réaliser une étape

Utilisez l’ [API GitBook](https://gitbook.com/docs/developers/gitbook-api/api-reference) avec un jeton d’accès personnel. Lorsque MCP est connecté, `search`, `describe_operation`, et `invoke_operation` permettent d’accéder à la plupart des opérations de l’API sans quitter la session.

## Vous êtes bloqué ou vous avez repéré une erreur ?

* **Posez la question à la documentation.** Envoyez une requête GET à l’URL de n’importe quelle page de documentation GitBook se terminant par `.md`, avec `ask` définissez sur votre question et `goal` définissez sur ce que la personne souhaite accomplir. Par exemple : `https://gitbook.com/docs/setup.md?ask=<question>&goal=<goal>`.
* **Signalez-le.** Une fois le MCP connecté, appelez `report_tool_feedback` en indiquant ce que vous avez essayé et ce qui s’est passé. N’incluez ni jetons ni contenu privé.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/fr/setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
