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.
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.
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.
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).
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.
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).
Let's assume you have created a space with two releases:
"Stable" (the main release), with a path set to
"Dev", a secondary release, with a path set to
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,
dev. Any updates on GitHub to these branches will reflect in the matching GitBook release. Any changes on GitBook will update the matching branches.
Let's assume you already have a repository on GitHub with two branches:
The default 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.
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
"v1", mapped to a branch
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.