GitBook allow you to have different versions of your content published at the same time, through the use of releases. Let's see that!

If you need to have different versions of your documentation published in parallel, because you offer different translations of your documentation, or because you want to document different versions of your product, GitBook has a feature for that: the releases.

What is a release

Conceptually, a release is like an alternate table of content. Each release contains independent pages organized in an independent table of contents. You can simply switch to another release using the dropdown at the top of the table of contents, and you will see all the content for that release.

When you create a new release in the editor, GitBook duplicate all pages you had and put them in the new release. This makes life easier if your releases are mostly similar. Afterward, any changes made to a page under a release B will not affect the pages in the release A it was based on. Releases evolve independently.

How to create a release

To create a release, you have to go in edit mode, and in the top of the TOC (left sidebar) you have a button Create a new release, click on it and it's done.

Create a new release

After creating a release, you can edit its path. A release's path will appear in URLs pointing to that release. It will also serve as branch names when using the GitHub integration (see the GitHub section below).

Usage examples

With releases you can document different versions of your product. It could be software versions for example. This has two advantages:

  • Your readers can still access older versions of your documentation, while you work on the latest version

  • You can improve and correct errors in older versions of your documentation even after releasing new versions of your product.

Releases can also be used to offer several translations of your documentation. That way, your readers can pick their preferred language, and then navigate in the documentation for that language naturally.

GitHub integration and releases

When using the GitHub integration, all releases will be mapped to branches on GitHub. When creating a new release from the GitBook editor, a matching branch will be created on GitHub. When creating a branch on GitHub, it will be imported as a release on GitHub if it matches your branch filter settings (see the GitHub integration setup).

A GitBook release is not the same thing as a GitHub release or tags. GitBook releases are mapped to GitHub branches.

Example: Starting from GitBook

Let's assume you have created a space with two releases:

  • "Stable" (the main release), with a path set to master

  • "Dev", a secondary release, with a path set to dev

Now you setup the GitHub integration for the first time on an empty repository, and choose to start with your content on GitBook. The two releases will be exported as branches on your repository, master and dev. Any updates on GitHub to these branches will reflect in the matching GitBook release. Any changes on GitBook will update the matching branches.

Example: Starting from GitHub

Let's assume you already have a repository on GitHub with two branches:

  • The default branch master

  • A branch v2 for a new version you are working on

Now you create a brand new space, and decide to setup the GitHub integration for the first time, by choosing to start with your content on GitHub. If you configure your branch filter as master v* the master branch will be sync, as well as all branches starting with v , this includes the second branch v2. So both branches will be exported as releases on GitBook. The branch master being the default branch of your repository will be chosen as the main release.

Example: Creating branches and creating releases

As a last example, let's say you have already setup the GitHub integration with a branch filter set to master v* and with the following releases:

  • "Stable" (the main release), mapped to the branch master

  • "v1", mapped to a branch v1

Now, if you create a new release with a path beta, it will create a beta branch on GitHub. Any changes to the beta branch will be tracked an synchronized, even it its name does not match the branch filter.

If you create a branch v2 on GitHub, it will be imported as release, because it matches the branch filter, and it will be tracked.

If you create a branch alpha on GitHub, it will be ignore by GitBook, because it does not match the branch filter.