Versioning

​

Setup

Add "versions": ["v2", "v1"] to your layout.json file where “v1” and “v2” are the names of your versions. You can put any number of versions in this array.

​

Versioning Options

You can add version values to anchors, groups, or individual pages.

​

Anchors

You can hide an entire anchor based on a version. This is useful when you have dozens of pages you want to hide. For example, for an API reference section.

Simply add version to your anchor. Anchors without a version value are shown in every version.

"anchors": [
    {
        "name": "API Reference V1",
        "url": "v1/api-reference",
        "version": "v1"
    },
    {
        "name": "API Reference V2",
        "url": "v2/api-reference",
        "version": "v2"
    },
    {
        "name": "Anchor Without a Version",
        "url": "example-anchor"
    }
]

You don’t need to add v1/ or v2/ to the start of your URLs, but some customers do it to keep their doc files organized.

​

Groups

You can version specific groups. This is useful when a few pages changed but everything else stayed the same.

Simply add version to your groups. Groups without a version value are shown in every version.

In the example below, pages in Nested Group V1 only show up when v1 docs are shown.

"navigation": [
    {
        "group": "Group without a version",
        "pages": [
            {
                "group": "Nested Group V1",
                "pages": ["page-with-version", "other-page-with-version"],
                "version": "v1"
            },
            {
                "group": "Nested Group Always Shows",
                "pages": ["nested-page", "other-nested-page"],
            },
            "page"
        ]
    }
]

​

Pages

You can version a single page. Add version to the top of your page metadata like so:

---
title: "My page title"
description: "My page description"
version: "v1"
---

Your navigation config in layout.json should include the page like normal, but the page will only show up when the correct version is selected.

​

Reusable Pages

Not all content has to be hidden though! Any content without a version value shows up in every version so you never duplicate content!

​

Troubleshooting

Common errors and how to fix them