FAQ

I have a GitHub sync error

In case of errors, make sure that:

  • Your repository has a README.md file at its root (or at the root folder specified in your .gitbook.yaml). This file is required and is used as the homepage for your documentation. For more details, refer to our content configuration.

  • If you have YAML frontmatters in your Markdown files, make sure they are valid using a YAML linter

Do not hesitate to contact us if you still have troubles, it might be a bug or something we can improve in GitBook.

GitBook is not using my docs folder?

By default, GitBook uses the root of the repository as a starting point. A specific directory can be specified to scope the markdown files. See Configuration.

GitBook is creating new markdown files?

When synchronizing and editing from GitBook with an existing GitHub repository, GitBook may create new markdown files instead of using the existing one.

My repository is not listed?

If you do not see some of the repositories that you can access on GitHub, like those of an organization you are part of, check the GitBook OAuth application settings page on GitHub. You will be able to grant (or request for) the GitBook OAuth app access to these repositories in a simple click.

GitBook OAuth application settings on GitHub

Nothing happens on GitBook after adding a new file to my repository

If your GitHub repository does not include a SUMMARY.md file, this article is not for you. Note that if you edited your content from GitBook at least once after setting up the GitHub sync, GitBook should have created this file automatically.

If after updating your GitHub repository by adding or modifying a markdown file, you do not see the update reflected on GitBook and the sidebar doesn't indicate an error during the sync, your modified file(s) is probably not listed in your SUMMARY.md file.

Either because you created it manually, or because you made an edit on GitBook and the GitBook to GitHub export phase of the sync created it for you, your repository should include a SUMMARY.md file at the root of your documentation folder.

The content of this file mirrors your main Table of Contents on GitBook and is used during the GitHub to GitBook import phase of the sync to recreate your ToC and reconciliate upcoming updates from GitHub with your existing content on GitBook.

If after ensuring that all your files are included in the SUMMARY.md file there's still nothing happening on GitBook, don't hesitate to contact us for more information.