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.
🧠 Note: Each variant contains independent pages organized in an independent table of content. Variants evolve independently.
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.
🧙♂ Tips: You can simply switch to another variant using the dropdown at the top of the table of content, and you will see all your content for that variant. ✨
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).
🧠 Note: A GitBook variant is not the same thing as a GitHub release or tags. GitBook variants are mapped to GitHub branches.
Let's assume you have created a space with two variants:
"Stable" (the main variant), with a path set to master
"Dev", a secondary variant, with a path set to dev
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, master
and 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 master
A 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 master
"v1", mapped to a branch v1
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.