Content configuration
If you’d like to configure GitSync further, you can add a .gitbook.yaml
file at the root of your repository to tell GitBook how to parse your Git repository.
Here’s an example:
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:
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:
Summary
The summary
file is a Markdown file (.md
) that should have the following structure:
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.
Redirects
While we recommend using site redirects when migrating your content into GitBook, you can also define redirects in your .gitbook.yaml
configuration file.
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.
Restructuring your content in GitBook
When moving your content within GitBook, most URLs should work as expected depending on complexity of the change. There are a number of tools that will allow you to verify which links were broken, if any.
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.
How to create a redirect
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 a past url /help
to a new url /support
How to redirect on a more complex path:
Original URL: https://docs.company.com/help
which has now moved to https://docs.company.com/misc/support
on GitBook.
The path misc/support.md
needs to be a real existing path within the repository. It needs to be relative to the current root
setting in.gitbook.yaml
.
Please don’t add any leading slashes. For example, ./misc/support.md
will not work.
Troubleshooting
The YAML file needs to be correctly formatted for the redirects to work. Errors such as incorrect indentation or whitespace can result in your redirects not working. Validating your YAML file can ensure that the redirects will work smoothly.
It's also important to consider that as long as a page exists for a path, GitBook won’t be looking for a possible redirect. So if you're setting up a redirect for an old page to a new one, you will need to remove the old page in order for the redirect to work.
Last updated