Important differences

Last updated 4 months ago

Differences that you should be aware of before migrating from legacy.gitbook.com to the new GitBook.

Please read on carefully before confirming migrating completely your projects. In doubt, contact us through Intercom and we will happily work with you to make your migration as smooth as possible.

CLI toolchain

We have moved away from the static site generator model, and no longer use the famous gitbook CLI to build documentation output. This has brought a lot of benefits and simplicity to the new version, such as instant publishing, getting rid of obscure build failures, automatic updates and continuous improvement of features for hosted documentations. This admittedly has some drawbacks. The main one being that you can no longer host a GitBook generated documentation yourself. On-premises version of GitBook.com as a service infrastructure was not planned before, and still isn't. If this is an issue for you, we will be happy to hear you, through our support messaging, or our feature request forum.

Git hosting and integration

We are no longer versioning your books as a Git repository. With the new version, we have shifted to a GitBook specific versioning system. Your content is still backed-up, versioned, and always available for export, so it is never locked on our platform. But we no longer offer this feature in the form of a git hosting service.

If you need your documentation to be accessible as a Git repository, you can always use our GitHub integration. For now, we do not support other git hosting services, such as GitLab.

AsciiDoc support

The new version has dropped support for AsciiDoc, and now only support an extended Markdown syntax. Supporting both AsciiDoc and Markdown as an input and output format has made our work unnecessarily harder in the past. This design redundancy was offering only slight benefits while reducing the overall quality of all our features. If this seems blocking for you at first, we hope that the number and quality of our future features will make up for it, and that the AsciiDoc versus Markdown question will soon be forgotten as a non-issue.

PDF and other ebook formats exports

The new version of GitBook no longer supports exporting to PDF and other ebooks format. A lot of rich-content does not translate well from the Web to PDF. GitBook will expose a developer API for people to consume and extend their content. It is not excluded that someone build a PDF export tool using the API, but it will not be officially supported. See the section about offline access if this is the part you cared about.

Offline access

Offline access, if relevant, might be implemented officially in the future. It will not be in the form of a static format exports though (such as PDF). If this is a feature you would like to see in GitBook, we are interested in hearing your use case.

Watching and starring books

You can no longer star, or watch books (which are now called spaces) in the new version. Notifications for a space will be brought back in the future for members of the space's organization, since they are useful for teams to keep up with important changes.

Desktop app

The new version does not currently have a desktop editor app. Our efforts are concentrated on the web version so we can focus on quality and reliability first. We are considering releasing a Desktop app in the future, but we have no public release-date at this time. If your space is synchronized with a GitHub repository, you can still edit the repository with your editor of choice.

Custom CSS

Custom CSS has lots of cons, for both authors and us. For authors, custom CSS requires coding skills, learning how GitBook is structured and stay updated on how it evolves as we add features. You’d also have to think about all the use cases: mobile, tablet, desktop and all the different states. For us, it means we’d have to develop and maintain an API that developers can rely on. We’d also need to keep retro compatibility in mind every time we rework something or add new features.

Instead, we prefer to offer customization options that we officially support, and that is easy to use for everyone. We are aware that the current options are limited right now but plan to add more in the future. Please tell us more about your use case so we can decide on what options to add.

Plugins

In general, the plugin system no longer exists. However, important plugins have become first-class features in the new version. Here is a non-exhaustive list:

  • Syntax highlighting (prism)

  • Image captions (image-captions)

  • Heading anchors (headings)

  • Easily selecting code snippet content (copy-code)

  • Algolia's search (algolia, lunr)

  • Google Analytics (ga)

  • Edit on GitHub button (github, github-buttons)

  • Page's table of content (atoc, toc)

  • Code block filename/tabs (codeblock-filename, code-tabs)

The syntax of some plugins are still supported in Markdown (see the list).

Some plugins are being considered to be implemented in the future as well. Here is an updated list of those plugins:

  • Support for math (mathjax or katex plugins)

Open a feature request in Canny if you want to see a plugin's feature implemented in GitBook.

GitHub

See the limitations when importing/exporting to markdown files of a GitHub repository.

Multi-language books

The previous version of GitBook allowed having a language selector on the homepage, to choose between different translations of the same book. This is not yet supported. But this is a planned feature of the new GitBook, and it will be compatible with previous configurations.

Editing Markdown source

The new GitBook editor does not offer a way to edit the Markdown source of documents. We no longer store Markdown or HTML, instead we store rich JSON data structures. The reason for this change is that Markdown has limited features. You cannot create tabs, complex tables, styled hints and so on. With the new GitBook, we want to offer all the elements our users need to write their documentation. We're focused on building an editor that is both easy to use and powerful with shortcuts for advanced users. For example, pressing # and space will turn the block into a H1, just like Markdown would.

With that being said, you can continue editing Markdown files through the GitHub integration and your favourite editor. The experience of editing complex blocks might not be perfect for now though, since it relies on a custom syntax.