Arbitrary HTML content in Markdown is not supported. GitBook will parse some of it, but it will mostly be ignored. You can still use HTML, but assume GitBook will ignore it.

Legacy Plugins

The syntax of the following plugins are still supported and have become first-class features of GitBook:

  • youtube

  • hint

  • theme-api

But plugins in general are no longer supported. Read more about plugins in the important differences section.

Git Tags

The GitHub integration synchronize Git branches as versions, but doesn't support synchronizing Git tags. The workaround is to also track your tags as branches:

git checkout -b v1.0 v1.0


It's not possible for GitBook to always synchronize concurrent changes made on GitBook and GitHub. Here are things you need to keep in mind when using the GitHub integration and you edit your content indifferently on both platforms:

  • All changes are always preserved in either GitBook's or GitHub's history. It will always be possible to recover your content on either platform.

  • In case of GitHub sync errors, or changes made in parallel on GitBook and GitHub within a few minutes timeframe, there are risk to see changes being reverted. This means that the changes are in either GitBook's or GitHub's history, but the last version will lack changes made by some party.

In Git terms, GitBook will never rewrite the Git history, it will only ever do merges, and in the worst case will favor one side over the other.

Common Errors

Most of the time, errors can be split into two categories: parsing errors and timeouts. 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.

  • The parser failed to read the configuration from the .gitbook.yaml file. Similar to the error above, check that the YAML is properly formatted thanks to a YAML linter. Additionally, make sure the configuration is valid by referring to the documentation on content configuration.

Regarding timeouts, they only happen when a file exceeds a certain size. Note that the overall size of the repository doesn't matter since each file is parsed separately. 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.