A variant is an other version of your content.
For an API or a library, this has two advantages:
Your readers can still access older versions of your documentation, while you work on the latest one
You can improve and correct errors in older versions of your documentation even after releasing new versions of your product.
Variants are also be used to offer several translations of your documentation.
To create a variant, click on
New page in the ToC (left sidebar), then pick "New variant" in the popover.
When you create a new variant in the editor, GitBook duplicates all pages you had and puts them in the new variant.
Afterwards, any changes applied to a page of variant B will not affect the pages in variant A.
After creating a variant, you can edit its name. A variant's name will appear in URLs pointing to that variant. It will also serve as branch names when using the GitHub integration.
When using the GitHub integration, all variants will be mapped to branches on GitHub. When creating a new variant 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 GitBook if it matches your branch filter settings (see the GitHub integration setup).
Let's assume you have created a space with two variants:
"Stable" (the main variant), with a path set to
"Dev", a secondary variant, with a path set to
Now you set up the GitHub integration for the first time on an empty repository, and choose to start working on your content on GitBook. The two variants will be exported as branches to your repository,
dev. Any updates on GitHub to these branches will be reflected in the matching GitBook variant. 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 set up the GitHub integration for the first time, and choose to start working on your content on GitHub. If you configure your branch filter as
master v* the
master branch will be synced, as well as all branches starting with
v, this includes the second branch
v2. So both branches will be exported as variants on GitBook. The branch
master is the default branch of your repository and will be the main variant.
As the last example, let's say you have already set up the GitHub integration with a branch filter set to
master v* and with the following variant:
"Stable" (the main variant), mapped to the branch
"v1", mapped to a branch
Now, if you create a new variant with a name
beta, it will create a
beta branch on GitHub. Any changes made to the
beta branch will be tracked, even if its name does not match the branch filter.
If you create a branch
v2 on GitHub, it will be imported as variant, 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.