V2 differences

CLI toolchain

We have moved away from the static site generator model, and no longer use 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.

V2 cannot be self-hosted but is a cloud solution only. You can read everything about our terms and services in our docs.

Git hosting and integration

We don't version your books as a Git repository. With the GitBook v2, 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.

If you need your documentation to be accessible as a Git repository, you can always use our GitHub integration.

🍏 Offline access and Desktop App

PDF export is now supported will allow to access your contact offline. We are considering releasing a Desktop app in the future, but we have no public release-date at this time but would be happy to take your feedback onboard.

👀 Watching and starring books

Previously you could star or watch books, now you can follow comments left by other team members when reviewing you drafts before and after publishing by receiving notifications.

You chose whether to enable or disable these notifications.

🎨 Custom CSS

Custom CSS has lots of cons, for both authors and the varieties of use cases such as mobile, tablet, desktop and all the different states.

Instead, we prefer to offer customization options that we officially support, and that is easy to use for everyone. For now you the business plan offers you advanced branding such as:

  • Custom color for your headers

  • Custom fonts

  • Full logo

Feel free to suggest any other branding options you are missing!

🔌 Plugins

Previous plugins may not be supported anymore but 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

You can see all Github changes and improvements in the Github integration section.

🌎 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.

We now made it easier by allowing to add variants to your content. Variants are used as an alternative version of your content and may contain different translations on your docs.

The language of the UI cannot yet be changed but we are reviewing our options. Feel free to follow this feature request on Canny!

📚 AsciiDoc support

We don't support AsciiDocs but we do support an extended Markdown syntax.

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.

🖊 Editing Markdown source

We now store rich JSON data structures instead of storing Markdown or HTML meaning that the new GitBook editor does not offer a way to edit the Markdown source of documents.

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 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 favorite editor.