Content Configuration

Configure a specific synchronization

You can configure how GitBook should parse your Git repository using the.gitbook.yaml file that must rely on the root of your repository.‌

Here is an example:

.gitbook.yaml
root: ./
​structure:
readme: README.md
summary: SUMMARY.md​
redirects:
previous/page: new-folder/page.md

Root

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

.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 content. Its default value is ./README.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

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

Summary‌

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

‌# 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​
* [Yet another page](another-page.md)

Providing a summary is optional. 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.‌

Redirects

You can create custom redirects of a URL to a page by specifying the path to the corresponding file. The path is relative to the "root" option. For example, here's how you can tell GitBook to redirect users accessing /help to the support page: .gitbook.yaml

.gitbook.yaml
redirects:
help: ./support.md

Tips: The URL must not include the leading slash.

Here's how you can deal with a more complex URL:.gitbook.yaml

.gitbook.yaml
redirects:
help/contact: ./contact.md

Note: 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 eventually add a redirect.