Content Configuration

Last updated 2 months ago

Configure how GitBook should parse your Git repository using the .gitbook.yaml file.

Specific configuration for the GitHub synchronization can be defined in a .gitbook.yaml file that must rely at 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
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 at ./docs/product/SUMMARY.md.

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
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 an 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
redirects:
help: ./support.md

Note that the URL must not include the leading slash. Here's how you can deal with a more complex URL:

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

With Git, moving a file often results in the file being removed and a new one being created. It 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.