> 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/skill/write-docs.md).
# Rédiger et modifier la documentation
Rédigez, créez, modifiez et mettez en forme des pages de documentation GitBook dans des dépôts synchronisés avec Git, des IDE ou n’importe quel éditeur de texte. À utiliser dès qu’une tâche implique la création ou la modification d’une page Markdown GitBook, la rédaction ou la mise à jour
#### Quand utiliser cette compétence
Utilisez cette compétence lorsque vous travaillez avec la documentation GitBook via :
* Dépôts synchronisés avec Git (GitHub, GitLab)
* Éditeurs Markdown locaux
* Intégrations IDE
* Tout environnement où vous modifiez le contenu GitBook sous forme de fichiers plutôt que via l'interface GitBook
#### Référence rapide
**Structure du contenu GitBook**
GitBook organise le contenu en pages, espaces et collections :
* **Pages** sont des fichiers Markdown individuels qui composent votre documentation
* **Les espaces** sont des collections de pages organisées en un site de documentation
* **Les collections** sont des groupes d'espaces
**Structure des fichiers :**
```
/
.gitbook/
assets/ # Images et fichiers gérés par GitBook
includes/ # Blocs de contenu réutilisables
vars.yaml # Variables au niveau de l'espace
.gitbook.yaml # Configuration
README.md # Page d'accueil
SUMMARY.md # Table des matières
getting-started/
installation.md
quickstart.md
api-reference/
authentication.md
endpoints.md
```
**Champs du front matter (formulaire rapide) :**
```markdown
---
description: "Description de la page pour le SEO"
icon: book-open
hidden: true
vars:
page_variable: value
layout:
width: default # ou 'wide'
tableOfContents:
visible: true
pagination:
visible: true
---
```
**Variables et expressions :**
* Variables de l'espace : `/.gitbook/vars.yaml`
* Variables de page : front matter `vars:`
* Syntaxe des expressions : `space.vars.variableName`
**Blocs personnalisés les plus courants :**
* `{% tabs %}...{% endtabs %}` — pour les alternatives
* `{% hint style="..." %}...{% endhint %}` — encadrés (info/avertissement/danger/succès)
* `{% stepper %}...{% endstepper %}` — étapes séquentielles
* `......
` — contenu dépliable
**Liens :**
* Externes : `[texte](https://example.com)`
* Relatifs (dans le même espace) : `[texte](page.md)`, `[texte](../folder/page.md)`
* Interespaces (espaces différents) : `[texte](https://app.gitbook.com/s//)` — les chemins relatifs ne franchissent jamais les frontières d’un espace, et `/spaces//pages/` n’est pas une forme de lien valide. L’alias qualifié par l’organisation `https://app.gitbook.com/o//s//` se résout de la même manière — écrivez la forme courte, mais ne réécrivez ni ne vérifiez par lint l’une ou l’autre (`references/git-sync-serialisation.md`). Obtenez `` à partir de `GET /orgs/{orgId}/spaces` et `` à partir du champ `path` d'une page dans `GET /spaces/{spaceId}/content/pages`. Vous créez un nouveau site où l'espace cible n'existe pas encore ? Utilisez `XSPACE_` des sentinelles ; `configure-site` les résout après la création. Exemples complets : `references/markdown.md`.
* Les pages déplacées/renommées continuent de fonctionner — GitBook crée automatiquement une redirection à partir de l'ancien chemin.
**Rappels importants :**
* Lisez d'abord SUMMARY.md lorsque vous travaillez sur du contenu existant
* Testez dans GitBook après modification locale
* Gardez SUMMARY.md synchronisé avec votre arborescence de fichiers et les titres des pages
* Les spécifications OpenAPI doivent être téléversées via l'interface, l'API, MCP ou la CLI, et non intégrées dans le Markdown
#### Quand utiliser quel bloc
| Besoin | Utilisez | Pourquoi |
| ------------------------------------------- | --------------------------- | ------------------------------------------------- |
| Instructions séquentielles et ordonnées | `{% stepper %}` | Progression claire des étapes |
| Options alternatives (langues, plateformes) | `{% tabs %}` | L'utilisateur choisit sans encombrer la page |
| Informations facultatives ou détaillées | `` | Garde la page facile à parcourir |
| Avertissements ou conseils importants | `{% hint %}` | Encadré coloré (info/avertissement/danger/succès) |
| Comparaisons côte à côte | `{% columns %}` | Disposition parallèle (2 colonnes max) |
| Chronologie ou journal des modifications | `{% updates %}` | Entrées datées avec filtrage par étiquette |
| Cartes de navigation visuelles | `` | Grille de cartes cliquables |
| Fichiers téléchargeables | `{% file %}` | Fichier avec légende |
| Liens d'appel à l'action | `` | Bouton principal ou secondaire |
| Contenu réutilisable sur plusieurs pages | `{% include %}` | Source unique de vérité |
| Contenu dynamique | `` | Affiche les valeurs des variables |
**Portée des variables :**
| Si la variable est... | Définir dans... | Accéder avec... |
| ---------------------------- | --------------------- | ------------------------- |
| Utilisée sur plusieurs pages | `/.gitbook/vars.yaml` | `space.vars.variableName` |
| Spécifique à une seule page | Front matter `vars:` | `page.vars.variableName` |
#### Travailler avec du contenu existant
1. **Lisez d'abord SUMMARY.md** — table des matières complète et hiérarchie des fichiers
2. **S'il n'y a pas de SUMMARY.md** — parcourez directement la structure des répertoires
3. **Vérifiez .gitbook.yaml** — chemin racine, emplacements personnalisés de README/SUMMARY, redirections
4. **Vérifiez .gitbook/assets/** — images et fichiers téléversés
5. **Vérifiez .gitbook/vars.yaml** — variables au niveau de l'espace
#### Pièges courants
**Liens interespaces :**
* N'utilisez pas de chemins relatifs pour créer un lien vers une page dans un espace différent — ils ne se résoudront pas.
* N'utilisez pas `/spaces//pages/` — ce n'est pas un format de lien GitBook valide.
* Utilisez `https://app.gitbook.com/s//` à la place, où `` est le `path` champ de la page cible (depuis `GET /spaces/{spaceId}/content/pages`), et non son ID de page.
* Ne « corrigez » pas la forme qualifiée par l’organisation `https://app.gitbook.com/o//s//` lorsque vous la trouvez — c’est un alias valide, et normaliser entre les deux formes crée des changements inutiles avec Git Sync.
* Utilisez `XSPACE_` des sentinelles lorsque les ID d'espace ne sont pas encore connus (nouvel espace, pas encore créé).
**Organisation des fichiers :**
* Ne référencez pas deux fois le même fichier Markdown dans SUMMARY.md
* Conservez des chemins de fichiers cohérents entre SUMMARY.md et les emplacements réels des fichiers
* Lorsque vous renommez le titre d’une page (son `#` en-tête ou `title` frontmatter), mettez également à jour le texte du lien de SUMMARY.md pour cette page — il pilote la navigation de la barre latérale, la pagination et le texte des liens relatifs, et ne se mettra pas à jour tout seul. Ne sautez cette étape que si l’entrée de SUMMARY.md utilise intentionnellement la substitution du titre du lien entre guillemets (`[Titre principal de la page](page.md "Titre du lien de la page")`) pour afficher volontairement quelque chose de différent.
**Configuration :**
* Lorsque vous utilisez Git Sync, gérez README.md uniquement via votre dépôt
* Testez les redirections après avoir déplacé ou renommé des fichiers
**Blocs personnalisés :**
* Fermez toujours correctement les blocs (`{% endtab %}`, `{% endhint %}`, etc.)
* Faites correspondre exactement les balises d'ouverture et de fermeture
**Front matter :**
* Mettez toujours entre guillemets `description:` les valeurs contenant `:`, `#`, ou d'autres caractères significatifs en YAML — les caractères spéciaux non placés entre guillemets provoquent des échecs silencieux de Git Sync sans message d'erreur
* Mais n’exigez pas de guillemets à la réécriture : GitBook réémet les descriptions dans le style de scalaire YAML que son sérialiseur choisit, y compris les blocs repliés (`>-`). Validez que le frontmatter se parse, pas la manière dont il est écrit (`references/git-sync-serialisation.md`)
* Le front matter doit être tout en haut du fichier
#### Travailler avec Git Sync
Lorsque GitBook est synchronisé avec Git, les modifications circulent dans les deux sens — les changements Git mettent à jour GitBook, et les modifications de l'interface GitBook sont renvoyées vers Git sous forme de commit. Les conflits de fusion sont résolus dans Git.
**Bonnes pratiques :** faites les changements structurels via SUMMARY.md dans Git ; utilisez des workflows basés sur des branches pour les mises à jour importantes ; examinez les commits générés automatiquement par GitBook.
**Aperçu d'une branche poussée**
La règle des deux liens ci-dessous couvre le contenu poussé via une demande de modification. Lorsque vous poussez via **Git** à la place, l'équivalent est le statut du commit : ouvrir une pull request/merge request — ou pousser vers une branche qui en possède déjà une — amène GitBook à importer cette branche et à publier un statut contenant un lien vers un aperçu du site généré. **Donnez ce lien à l'utilisateur chaque fois que vous poussez des modifications de documentation, sans qu'il ait besoin de le demander.** Récupérez-le à partir du statut du commit plutôt que de construire une URL : l'ID de révision est généré au moment de l'importation et ne peut pas être déduit de la branche ou de la PR, et chaque push en génère un nouveau, donc un lien ancien devient obsolète. Voir `references/git-sync-previews.md` pour les commandes GitHub et GitLab et pour savoir quoi faire pendant que l'importation est encore en cours.
**Choisir entre Git Sync et un push de contenu via demande de modification**
Lorsqu'un espace est configuré avec Git Sync et que vous avez (ou pouvez obtenir) un clone local du dépôt synchronisé, **privilégiez la modification directe des fichiers puis le commit/push** — Git Sync propage la modification vers GitBook. Cela reste vrai même dans une session MCP où un outil de push de contenu via demande de modification (par ex. `updateChangeRequestContent`) est disponible et connecté : le fait que l'outil soit à une seule requête de distance n'est pas une raison pour contourner Git comme source de vérité. Un agent qui le découvre *peut* pousser directement dans une CR doit quand même vérifier si Git Sync est configuré et accessible avant de le faire.
Utilisez plutôt le chemin de push de contenu via demande de modification ( `updateChangeRequestContent` ou similaire, ou le REST `POST .../change-requests//content` endpoint — voir la `cr-create` compétence) lorsque :
* l'espace n'a pas encore Git Sync configuré (par ex. un espace tout neuf encore en cours de configuration),
* aucun clone Git local n'est disponible dans l'environnement actuel (pas d'accès au système de fichiers du dépôt synchronisé), ou
* la modification est petite et ciblée (une faute de frappe, un paragraphe, un champ) — ouvrir une CR est proportionné, et un cycle complet clone/commit/push n'en vaut pas la peine.
Pour tout ce qui est plus important — un nouvel arbre de pages, une réécriture multi-pages, une migration — privilégiez Git Sync, même si cela signifie faire une pause pour confirmer d'abord que le dépôt est cloné localement. Ne choisissez pas par défaut l'outil de demande de modification simplement parce que c'est celui qui a fonctionné en premier.
**Deux liens sont obligatoires dès qu'une demande de modification est impliquée**
Si une partie de cette modification est passée par une demande de modification (`create_change_request` / `updateChangeRequestContent`, ou les équivalents REST), **la modification n'est pas terminée tant que les deux éléments suivants n'ont pas été renvoyés, à chaque fois — c'est une règle stricte, pas un rappel à survoler :**
1. **Le lien du diff/de l'éditeur de la CR** — `urls.app` sur l'objet de demande de modification, renvoyé par `create_change_request`, `updateChangeRequestContent`, ou `getChangeRequestById`.
2. **Le lien d'aperçu du site** — l'URL du site depuis l' **objet** Site (`urls.published` lorsque le site est public, sinon `urls.preview`) avec **`/~/changes//` ajouté**. Cela ne fait jamais partie de la réponse de la demande de modification — cela nécessite une recherche séparée — et c'est précisément pour cela qu'il est souvent oublié. Résolvez-le à chaque fois, pas seulement quand cela vous revient à l'esprit. **Sans le `~/changes/` segment, le lien n'est pas un aperçu de la demande de modification** — il affiche le contenu actuel du site, donc il semblera plausible tout en étant erroné.
Cela s'applique quelle que soit la compétence qui a poussé le contenu (cette compétence ou `configure-site`) et quel que soit le transport (MCP ou REST). Voir le `cr-create` guide « Afficher le lien d'aperçu » de la compétence pour l'explication complète et les étapes de résolution REST. **Équivalent MCP** (GitBook MCP n'a pas d'appel unique prêt à l'emploi du type "donne-moi le lien d'aperçu") :
1. Déterminez l'organisation de l'espace — `invoke_operation("getSpaceById", {path:{spaceId}})` → `.organization` (ignorez cette étape si vous avez déjà l'ID de l'organisation).
2. Déterminez à quel site appartient l'espace — `list_sites` / `get_site_structure`, ou vérifiez les site-spaces de chaque site pour trouver une correspondance sur `.space.id`.
3. `invoke_operation("getSiteById", {path:{organizationId, siteId}})` → `.urls.published` (une fois le site en ligne), sinon `.urls.preview`. Ajoutez `/~/changes//`, en supprimant la barre oblique finale renvoyée par l'API.
Si l'espace n'est rattaché à aucun site publié, dites-le clairement et ne fournissez que le lien du diff — ne supprimez pas discrètement la ligne d'aperçu sans explication.
Cela a déjà échoué silencieusement en pratique : une modification a été poussée et fusionnée avec seulement le lien du diff signalé, et le lien d'aperçu n'est apparu que lorsqu'une personne l'a demandé directement. Considérez la checklist des deux liens ci-dessus de manière littérale.
#### Fichiers de référence
Chargez-les à la demande lorsque la tâche nécessite plus de détails :
* `references/blocks.md` — syntaxe complète et exemples détaillés pour chaque type de bloc GitBook : tabs, steppers, hints, expandable, columns, updates, cards, embeds, files, buttons, icons, contenu réutilisable et blocs OpenAPI. **Chargez-le lors de la rédaction de pages non triviales ou lorsque la référence rapide ci-dessus ne suffit pas.**
* `references/frontmatter.md` — tous les champs de front matter avec descriptions, règles de guillemets YAML, images de couverture, contenu adaptatif (`if:`), et l'approfondissement sur les variables/expressions. **Chargez-le lors de la configuration de la mise en page de la page, des couvertures, de la visibilité conditionnelle ou des variables.**
* `references/markdown.md` — Markdown standard, blocs de code avec titres, math/TeX, types de diagrammes Mermaid et exemples, ainsi que les particularités de gestion des SVG. **Chargez-le lorsque vous travaillez avec des diagrammes, des mathématiques ou des ressources SVG.**
* `references/configuration.md` — `.gitbook.yaml` options, la `.gitbook/` structure des répertoires (assets, includes, vars, tags), et les règles de grammaire de SUMMARY.md dans leur intégralité. **Chargez-le lors de la configuration d'un espace, de l'ajout de redirections, ou de la rédaction/modification de SUMMARY.md.**
* `references/git-sync-serialisation.md` — ce que GitBook réécrit lorsqu’il exporte un espace vers le dépôt : `description:` style de scalaire, forme d’URL de lien entre espaces, ré-serialisation des blocs, et la règle selon laquelle vous vérifiez la validité plutôt que la forme. **Chargez-le lorsqu’un diff Git Sync contient des changements que personne n’a faits à la main, ou avant d’écrire toute vérification ou étape de build qui valide le frontmatter ou les liens des docs.**
* `references/git-sync-previews.md` — obtenir un lien d'aperçu pour une branche poussée via Git Sync : lire le statut de commit GitBook sur GitHub et GitLab, distinguer l'aperçu du site du diff de l'éditeur, et gérer une importation encore en cours. **Chargez-le chaque fois que vous poussez des modifications de documentation vers une branche avec une pull request/merge request ouverte.**
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://gitbook.com/docs/documentation/fr/skill/write-docs.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.