A variant is another 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.

Documenting different versions of your product using variants

Variants are also be used to offer several translations of your documentation.

🎭 Create a variant

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.

GitHub integration and variants

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.

Example: Starting from GitBook

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.

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

Example: Creating branches and creating variants

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.