Content configuration

Configure Git Sync through code

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.

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.

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:

gitbook-docs.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

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:

.gitbook.yaml

root: ./

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

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

Set the content root

Set root when a space’s content lives inside a subdirectory:

.gitbook.yaml

root: ./docs/

Paths in .gitbook.yaml are relative to root. With root: ./docs/, structure.summary: ./product/SUMMARY.md resolves to ./docs/product/SUMMARY.md.

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.

Set the first page and navigation file

Use structure.readme and structure.summary to set custom file paths:

.gitbook.yaml

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

When Git Sync is enabled, manage README.md files in your repository. Editing them in GitBook can create conflicts or duplicate pages.

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.

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:

SUMMARY.md

# Summary

## Product

* [Overview](README.md)
  * [Getting started](getting-started.md)
  * [Configuration](configuration.md)

## Reference

* [API reference](api.md)

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:

SUMMARY.md

# Summary

* [Page main title](page.md "Navigation label")

GitBook uses the page link title in the sidebar, pagination, and relative links. Without one, GitBook uses the page title.