Most of the time, errors can be split into three categories:
A parsing error can happen for three reasons:
The parser met a new Markdown edge case that is not supported yet. In this situation, double-check the Markdown syntax and let us know if everything looks fine.
The parser failed to parse the YAML front matter. To avoid this error, make sure that the YAML is properly formatted by using a YAML linter.
Regarding timeouts, they only happen when a file exceeds a certain size.
When facing a timeout, you might want to look for ways to split your large files into separate ones. With that being said, we are constantly working on improving performance so timeouts are very rare.
Since GitBook uses GitHub's API to perform actions on your repository using the GitBook OAuth app, it is subject to the GitHub rate limiting rules.
To prevent these errors, GitBook uses smart diffing logic to only import/export what was modified in your files when importing markdown from a GitHub commit and exporting your content on GitBook back to markdown. If the resulting number of files that were actually modified by a commit exceeds 2500, the import is currently automatically skipped to prevent affecting your rate limiting.
Even though we are doing our best to limit this effect, this kind of error can still happen, mainly in the following cases:
During an initial GitHub sync setup, it is possible to reach this limit since all the content needs to be initially imported to or exported from GitBook.
To prevent this to happen, you recommend setting up the sync as soon as possible, ideally when starting your documentation project.
When this is not possible, you can do the following to incrementally sync your content without hitting the rate limit.
The number of entries in the
SUMMARY.md file can also be reduced during the initial import, then increased in another commit to finally include all your pages.
When exporting from GitBook, try reducing the number of pages in your Table of Contents by publishing a new revision. Once the content has been exported to GitHub, rollback to the revision that includes all your content.
Since GitHub's API rate limiting is applied on a per-user basis, we recommend to use different GitHub accounts to sync your different spaces when possible.
Also make sure that you don't have any other 3rd party services (CI, Zapier, etc...) connected to the account used during the GitHub sync setup that could be performing operations on GitHub to reduce the risk.