> 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/docs-as-code/git-sync/content-configuration.md).

# Configuration du contenu

Configurez Git Sync par le code

Git Sync utilise trois fichiers. Choisissez le fichier qui contrôle la partie de Git Sync dont vous avez besoin :

* `gitbook-docs.yaml` configure le site et associe les espaces aux répertoires du dépôt.
* `.gitbook.yaml` configure la façon dont GitBook lit le contenu d’un espace.
* `SUMMARY.md` définit la navigation d’un espace.

### Configurez le site avec gitbook-docs.yaml

`gitbook-docs.yaml` configure l’ensemble du site. Il se trouve dans le répertoire du projet Git Sync. Si vous ne définissez pas de **répertoire du projet**.

Utilisez `gitbook-docs.yaml` pour définir la structure de votre site et associer chaque espace à un répertoire. Chaque élément de `site.structure` possède une `key`stable. Le `content.directory` d’un espace définit son répertoire dans le dépôt. Si un espace d’un site n’est pas synchronisé avec le dépôt du site, son `content.directory` est `null`.

#### Comprendre la configuration du site et de l'espace

`gitbook-docs.yaml` gère la structure globale du site et le mappage des répertoires. `.gitbook.yaml` configure le contenu d’un espace mappé.

Lorsque les deux fichiers sont présents, GitBook applique `gitbook-docs.yaml` en premier pour sélectionner le répertoire de l’espace. `.gitbook.yaml` configure ensuite le contenu de ce répertoire. Il ne peut pas remplacer le mappage global du site `content.directory` .

#### Les clés identifient vos espaces

Git Sync reconnaît chaque espace et chaque section grâce à sa `key`, et non à son titre, son chemin ou son répertoire. La clé permet à GitBook de faire correspondre une entrée de `gitbook-docs.yaml` au contenu existant d’une synchronisation à l’autre.

{% hint style="danger" %}
**Modifier la `key` d’un espace remplace cet espace.** GitBook considère l’ancienne clé comme supprimée et la nouvelle comme un nouvel espace. Il crée un nouvel espace, y importe votre contenu depuis le répertoire associé et conserve l’espace d’origine dans votre organisation, détaché du site.

Vos pages réapparaissent, mais dans un nouvel espace avec un nouvel ID d’espace. Les liens, cartes et appels d’API qui font référence à l’ancien ID ne se résolvent plus, et tout ce qui existe uniquement dans GitBook plutôt que dans votre dépôt reste dans l’espace d’origine.

Restaurer la clé d’origine n’annule pas cela. Cela crée un autre nouvel espace et y importe le contenu.
{% endhint %}

Vous pouvez choisir librement les clés lors de la création initiale d’une entrée, et GitBook les génère pour vous lors de l’enregistrement du mappage du contenu du site. Une fois qu’un espace est en ligne, considérez sa clé comme permanente :

* Pour renommer un espace, modifiez son `title`. La clé reste la même.
* Pour modifier l’URL d’un espace, modifiez son `path`. La clé reste la même.

Cet exemple associe les espaces anglais et français à des répertoires distincts :

{% code title="gitbook-docs.yaml" expandable="true" %}

```yaml
$schema: https://api.gitbook.com/gitbook-docs.yaml
site:
  title: Documentation
  structure :
    - type: section
      key: documentation
      title: Documentation
      path: documentation
      children:
        - type: space
          key: docs-en
          title: Anglais
          path: docs
          default: true
          content:
            directory: ./docs/en
            language: en
        - type: space
          key: docs-fr
          title: Français
          path: fr
          content:
            directory: ./docs/fr
            language: fr
```

{% endcode %}

<details>

<summary>Configurez des propriétés supplémentaires du site</summary>

Utilisez ces propriétés facultatives pour affiner la structure de votre site :

| Propriété              | À utiliser pour                                                          |
| ---------------------- | ------------------------------------------------------------------------ |
| `type: section-group`  | Regrouper des sections liées sous un même titre de navigation.           |
| `description`          | Ajouter une description à une section.                                   |
| `icon`                 | Ajouter une icône à une section ou à un groupe de sections.              |
| `localizedTitle`       | Traduire le titre d’une section, d’un groupe de sections ou d’un espace. |
| `localizedDescription` | Traduire la description d’une section.                                   |
| `hidden`               | Masquer un espace de la navigation du site.                              |

GitBook crée ou met à jour `gitbook-docs.yaml` lorsqu’il enregistre le mappage du contenu du site.

</details>

### Configurez un espace avec .gitbook.yaml

`.gitbook.yaml` configure un espace. Il se trouve dans le répertoire associé à cet espace. Utilisez-le pour définir la racine du contenu, la première page, le fichier de navigation et les redirections.

Par exemple, si un espace est mappé vers `./docs`, placez le fichier dans `./docs/.gitbook.yaml` et conservez `root: ./` sauf si le contenu se trouve dans un sous-répertoire. Si un espace est mappé vers la racine du dépôt et que son contenu se trouve dans `./docs`, placez `.gitbook.yaml` à la racine du dépôt et définissez `root: ./docs/`.

Les principaux réglages sont :

* `root` définit le répertoire lu par GitBook. Par défaut, il s’agit de `./`.
* `structure.readme` définit la première page. Par défaut, il s’agit de `README.md`.
* `structure.summary` définit le fichier de navigation. Par défaut, il s’agit de `SUMMARY.md`.
* `redirects` associe les anciens chemins aux nouveaux chemins dans l’espace.

Voici une configuration typique :

{% code title=".gitbook.yaml" %}

```yaml
root: ./

structure :
  readme: README.md
  summary: SUMMARY.md

redirects:
  previous/page: new-folder/page.md
```

{% endcode %}

#### Définissez la racine du contenu

Définissez `root` lorsque le contenu d’un espace se trouve dans un sous-répertoire :

{% code title=".gitbook.yaml" %}

```yaml
root: ./docs/
```

{% endcode %}

{% hint style="warning" %}
Les chemins dans `.gitbook.yaml` sont relatifs à `root`. Avec `root: ./docs/`, `structure.summary: ./product/SUMMARY.md` correspond à `./docs/product/SUMMARY.md`.
{% endhint %}

Dans un monorepo, `root` s’applique uniquement au répertoire de l’espace indiqué. Il ne rend pas accessibles les répertoires voisins. Pour les configurations de dépôts comportant plusieurs espaces, consultez [Monorepos](https://gitbook.com/docs/documentation/fr/docs-as-code/git-sync/monorepos.md).

#### Définissez la première page et le fichier de navigation

Utilisez `structure.readme` et `structure.summary` pour définir des chemins de fichiers personnalisés :

{% code title=".gitbook.yaml" %}

```yaml
structure :
  readme: ./product/README.md
  summary: ./product/SUMMARY.md
```

{% endcode %}

{% hint style="warning" %}
Lorsque Git Sync est activé, gérez les fichiers `README.md` dans votre dépôt. Les modifier dans GitBook peut créer des conflits ou des pages en double.
{% endhint %}

#### Configurez les redirections

Configurez les redirections au niveau de l’espace dans `.gitbook.yaml`. Les chemins de redirection s’appliquent uniquement à cet espace.

Vous pouvez également gérer les redirections au niveau du site dans l’application GitBook. Consultez [Redirections du site](https://gitbook.com/docs/documentation/fr/publish/site-redirects.md).

### Configurez la navigation avec SUMMARY.md

`SUMMARY.md` définit la table des matières d’un espace. GitBook le recherche dans le répertoire `root` configuré.

Si GitBook ne trouve pas `SUMMARY.md`, il déduit la navigation à partir de vos dossiers et fichiers Markdown. GitBook crée ou met à jour `SUMMARY.md` lorsque vous modifiez la navigation dans GitBook.

Utilisez des titres de niveau 2 pour les groupes de pages et des liens imbriqués pour les pages enfants. Chaque lien de premier niveau après un titre de groupe de pages appartient à ce groupe jusqu’au prochain titre de groupe de pages. Une règle horizontale ne ferme pas un groupe, donc placez les pages de premier niveau non regroupées avant le premier groupe :

{% code title="SUMMARY.md" %}

```markdown
# Résumé

## Produit

* [Aperçu](README.md)
  * [Prise en main](getting-started.md)
  * [Configuration](configuration.md)

## Référence

* [Référence de l’API](api.md)
```

{% endcode %}

Chaque fichier Markdown ne peut apparaître qu’une fois dans `SUMMARY.md`. Une page ne peut avoir qu’une seule URL dans un espace.

#### Définissez les libellés de navigation

Ajoutez un titre de lien de page lorsque le libellé de navigation diffère du titre de la page :

{% code title="SUMMARY.md" %}

```markdown
# Résumé

* [Titre principal de la page](page.md "Libellé de navigation")
```

{% endcode %}

GitBook utilise le titre du lien dans la barre latérale, la pagination et les liens relatifs. Il ne modifie pas le slug ni l'URL de la page. Sans titre de lien, GitBook utilise le titre de la page.

#### Lien vers des URL absolues

`SUMMARY.md` prend en charge les URL absolues pour la navigation externe et entre espaces :

{% code title="SUMMARY.md" %}

```markdown
# Résumé

* [GitBook](https://gitbook.com)
* [Référence de l'API](https://app.gitbook.com/s/<spaceId>/api-reference)
```

{% endcode %}

Utilisez une URL GitBook absolue pour créer un lien vers une page d’un autre espace. Remplacez `<spaceId>` par l’ID de l’espace cible.


---

# 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/docs-as-code/git-sync/content-configuration.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.
