> 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/docs-as-code/git-sync/content-configuration.md).
# Content configuration
Git Sync uses three files. Choose the file that controls the part of Git Sync you need:
* `gitbook-docs.yaml` configures the site and maps spaces to repository directories.
* `.gitbook.yaml` configures how GitBook reads one space’s content.
* `SUMMARY.md` defines a space’s navigation.
### Configure the site with gitbook-docs.yaml
`gitbook-docs.yaml` configures the entire site. It lives in the Git Sync Project directory. GitBook uses the repository root when you don't set a **Project directory**.
Use `gitbook-docs.yaml` to define your site structure and map each space to a directory. Each item in `site.structure` has a stable `key`. A space’s `content.directory` sets its repository directory. If a space in a site does not sync to the site’s repository, its `content.directory` is `null`.
#### Keys identify your spaces
Git Sync recognizes each space and section by its `key`, not by its title, path, or directory. The key is how GitBook matches an entry in `gitbook-docs.yaml` to existing content from one sync to the next.
{% hint style="danger" %}
**Changing a space’s `key` replaces that space.** GitBook treats the old key as removed and the new key as a new space. It creates a new space, imports your content into it from the mapped directory, and leaves the original space in your organization, detached from the site.
Your pages come back, but in a new space with a new space ID. Links, cards, and API calls that reference the old ID stop resolving, and anything that exists only in GitBook rather than in your repository stays with the original space.
Restoring the original key doesn’t undo this. It creates another new space and imports into that one.
{% endhint %}
Keys are safe to choose freely when you first create an entry, and GitBook generates them for you when it saves the site content mapping. Once a space is live, treat its key as permanent:
* To rename a space, change its `title`. The key stays the same.
* To change a space’s URL, change its `path`. The key stays the same.
This example maps English and French spaces to separate directories:
{% 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: English
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 %}
Configure additional site properties
Use these optional properties to refine your site structure:
| Property | Use it for |
| ---------------------- | --------------------------------------------------------- |
| `type: section-group` | Group related sections under a shared navigation heading. |
| `description` | Add a description to a section. |
| `icon` | Add an icon to a section or section group. |
| `localizedTitle` | Translate a section, section group, or space title. |
| `localizedDescription` | Translate a section description. |
| `hidden` | Hide a space from site navigation. |
GitBook creates or updates `gitbook-docs.yaml` when it saves the site content mapping.
### Configure a space with .gitbook.yaml
`.gitbook.yaml` configures one space. It lives in that space’s mapped directory. Use it to set the content root, first page, navigation file, and redirects.
The main settings are:
* `root` sets the directory GitBook reads. It defaults to `./`.
* `structure.readme` sets the first page. It defaults to `README.md`.
* `structure.summary` sets the navigation file. It defaults to `SUMMARY.md`.
* `redirects` maps old paths to new paths within the space.
Here is a typical configuration:
{% code title=".gitbook.yaml" %}
```yaml
root: ./
structure:
readme: README.md
summary: SUMMARY.md
redirects:
previous/page: new-folder/page.md
```
{% endcode %}
#### Set the content root
Set `root` when a space’s content lives inside a subdirectory:
{% code title=".gitbook.yaml" %}
```yaml
root: ./docs/
```
{% endcode %}
{% hint style="warning" %}
Paths in `.gitbook.yaml` are relative to `root`. With `root: ./docs/`, `structure.summary: ./product/SUMMARY.md` resolves to `./docs/product/SUMMARY.md`.
{% endhint %}
In a monorepo, `root` only applies inside the mapped space directory. It doesn’t make sibling directories available. For multi-space repository setups, see [Monorepos](/docs/docs-as-code/git-sync/monorepos.md).
#### Set the first page and navigation file
Use `structure.readme` and `structure.summary` to set custom file paths:
{% code title=".gitbook.yaml" %}
```yaml
structure:
readme: ./product/README.md
summary: ./product/SUMMARY.md
```
{% endcode %}
{% hint style="warning" %}
When Git Sync is enabled, manage `README.md` files in your repository. Editing them in GitBook can create conflicts or duplicate pages.
{% endhint %}
#### Configure redirects
Configure space-level redirects in `.gitbook.yaml`. Redirect paths only apply within that space.
You can also manage site-level redirects in the GitBook app. See [Site redirects](/docs/publish/site-redirects.md).
### Configure navigation with SUMMARY.md
`SUMMARY.md` defines a space’s table of contents. GitBook looks for it in the configured `root` directory.
If GitBook doesn't find `SUMMARY.md`, it infers navigation from your folders and Markdown files. GitBook creates or updates `SUMMARY.md` when you change navigation in GitBook.
Use headings for page groups and nested links for child pages:
{% code title="SUMMARY.md" %}
```markdown
# Summary
## Product
* [Overview](README.md)
* [Getting started](getting-started.md)
* [Configuration](configuration.md)
## Reference
* [API reference](api.md)
```
{% endcode %}
Each Markdown file can appear once in `SUMMARY.md`. A page can only have one URL in a space.
#### Set navigation labels
Add a page link title when the navigation label differs from the page title:
{% code title="SUMMARY.md" %}
```markdown
# Summary
* [Page main title](page.md "Navigation label")
```
{% endcode %}
GitBook uses the page link title in the sidebar, pagination, and relative links. Without one, GitBook uses the page title.
---
# 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/docs-as-code/git-sync/content-configuration.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.