Skip to main content
If you’d like to configure Git Sync further, you can add a .gitbook.yaml file at the root of your repository to tell GitBook how to parse your Git repository.

​
Basic configuration

Here’s a basic example of a .gitbook.yaml configuration file:
.gitbook.yaml
root: ./

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

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

​
Root

The path to lookup for your documentation defaults to the root directory of the repository. Here’s how you can tell GitBook to look into a ./docs folder:
.gitbook.yaml
root: ./docs/
All other options that specify paths will be relative to this root folder. So if you define root as ./docs/ and then structure.summary as ./product/SUMMARY.md, GitBook will actually look for a file in ./docs/product/SUMMARY.md.

​
Structure

The structure accepts two properties:
  • readme: Your documentation’s first page. Its default value is ./README.md
  • summary: Your documentation’s table of contents. Its default value is ./SUMMARY.md
The value of those properties is a path to the corresponding files. The path is relative to the “root” option. For example, here’s how you can tell GitBook to look into a ./product folder for the first page and summary:
.gitbook.yaml
structure:
  readme: ./product/README.md
  summary: ./product/SUMMARY.md
When Git Sync is enabled, remember not to create or modify readme files through GitBook’s UI. The readme file should be managed exclusively in your GitHub/GitLab repository to avoid conflicts and duplication issues.

​
Summary file format

The summary file is a Markdown file (.md) that should have the following structure:
SUMMARY.md
# Summary

## Use headings to create page groups like this one

* [First page's title](page1/README.md)
    * [Some child page](page1/page1-1.md)
    * [Some other child page](part1/page1-2.md)

* [Second page's title](page2/README.md)
    * [Some child page](page2/page2-1.md)
    * [Some other child page](part2/page2-2.md)

## A second-page group

* [Another page](another-page.md)
Providing a custom summary file is optional. By default, GitBook will look for a file named SUMMARY.md in your root folder if specified in your config file, or at the root of the repository otherwise. If you don’t specify a summary, and GitBook does not find a SUMMARY.md file at the root of your docs, GitBook will infer the table of contents from the folder structure and the Markdown files below.
The summary markdown file is a mirror of the table of contents of your GitBook space. So even when no summary file is provided during an initial import, GitBook will create one and/or update it whenever you update your content using the GitBook editor.Because of this, it’s not possible to reference the same Markdown file twice in your SUMMARY.md file, because this would imply that a single page lives at two different URLs in your GitBook space.

​
Table of contents titles

If you want your pages to have a different title in the table of contents sidebar than on the page itself, you can define an optional page link title in your SUMMARY.md file. If you’re using Git Sync, the page link title is set on the page link:
SUMMARY.md
# Summary

* [Page main title](page.md "Page link title")
The text inside the quotes ("Page link title") will be used:
  • In the table of contents (sidebar)
  • In the pagination buttons at the bottom of each page
  • In any relative links you add to that page
Page link titles are optional — if you don’t manually add one, GitBook will use the page’s standard title everywhere by default.

​
Redirects

Redirects allow you to define redirects in your .gitbook.yaml configuration file. The path is relative to the “root” option. For example, here’s how you can tell GitBook to redirect users accessing a past url /help to a new url /support
.gitbook.yaml
root: ./

redirects:
  help: support.md
Redirects you define in a space’s configuration file are scoped to the corresponding space. We recommend creating site redirects for most cases as they apply to the whole site, across spaces.
With Git, when a file is moved many times, the file is removed and a new one is created. This makes it impossible for GitBook to know that a folder has been renamed, for example. Make sure to double-check and add redirects where needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us