Limitations

HTML

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.

Plugins

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

  • youtube

  • hint

  • theme-api

Feel free to suggest any other plugins that you might be missing on Canny.

Git Tags

The GitHub integration synchronizes 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

Synchronization

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 when 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 is a 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.