These guides will assume v1 pages are in a folder named v1, v2 pages are in a folder named v2, and so on. While this method of structuring your files isn’t strictly necessary, it’s a great way to keep your files organized.

​
Setup

Add "versions": ["v2", "v1"] to your mint.json file where v1 and v2 are the names of your versions. You can put any number of versions in this array. The first version from the array serves as the default version.

The versions dropdown will show your versions in the order you include them in mint.json.

​
Versioning Groups and Pages

The best way to specify page versions is by adding a version value to a group in the navigation. When you specify the version of a group, that version is applied to all pages within that group.

You can also specify the version of a single page in the page metadata. Versions on individual pages always take precedence.

"navigation": [
  {
    "group": "Getting Started",
    "version": "v1",
    "pages": [...]
  }
],

While it is possible to nest versioned groups within versioned groups, it is not recommended. If you do take this approach, the more deeply-nested version takes precedence.

​
Versioning Tabs and Anchors

You can hide a tab or anchor based on a version. This is useful if you have links that are only relevant in one version. Importantly, this does not apply the version to the pages within that anchor.

In mint.json, simply add version to your tab or anchor. Tabs and anchors without a specified version are shown in every version.

"tabs": [
  {
    "name": "API Reference V1",
    "url": "v1/api-reference",
    "version": "v1"
  },
  {
    "name": "API Reference V2",
    "url": "v2/api-reference",
    "version": "v2"
  },
  {
    "name": "Migrating from V1 to V2",
    "url": "https://mintlify.com/changelog/v2"
  },
],

​
Sharing Between Versions

Not all content has to be hidden though! Any content without a specified version appears in every version so you don’t have to duplicate content!

​
Troubleshooting

Common errors and how to fix them