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
1
root: ./
2
​
3
​structure:  
4
    readme: README.md  
5
    summary: SUMMARY.md​
6
​
7
redirects:  
8
    previous/page: new-folder/page.md
Copied!
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
1
root: ./docs/
Copied!
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 ./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
1
structure:  
2
    readme: ./product/README.md
3
    summary: ./product/SUMMARY.md
Copied!
​Summary‌
The summary file is a Markdown file (.md) that should have the following structure:
1
‌# Summary​
2
​
3
## Use headings to create page groups like this one​
4
​
5
* [First page's title](page1/README.md)    
6
    * [Some child page](page1/page1-1.md)    
7
    * [Some other child page](part1/page1-2.md)
8
​
9
* [Second page's title](page2/README.md)    
10
    * [Some child page](page2/page2-1.md)    
11
    * [Some other child page](part2/page2-2.md)    
12
​
13
## A second-page group​
14
​
15
* [Yet another page](another-page.md)
Copied!
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.
Due to this, it is 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.
​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
1
redirects:  
2
    help: support.md
Copied!
Why would you need a redirect?
You may be migrating your docs from a different service to GitBook. It's common to also restructure some of your content along the process. Assuming you had the following URL in your old docs:
https://docs.company.com/help
and that has now moved to https://docs.company.com/misc/support on GitBook.
Here's how to include a redirect for that scenario:
.gitbook.yaml
1
redirects:
2
    help: misc/support.md
Copied!
The path misc/support.md needs to be a real existing path within the repository. It needs to be relative to the current root settting in .gitbook.yaml. Please don't add any leading slashes. For example, ./misc/support.md will not work.
Please don't add any leading slashes to the old URL path help. For example, /help will not work.
Here's how you can deal with a more complex URL for the old path:
.gitbook.yaml
1
redirects:  
2
    help/contact: contact.md
Copied!
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.