Add versioned content

You can set up your project to maintain multiple concurrent versions of documents or API description files. It is possible to apply versioning to single files or sets of files in the same location. You can do this by creating version subfolders for each version of content you want to include.

When you access content inside a version subfolder, a version picker is displayed at the top of the sidebar. The version picker enables users to select which version of content to display.

You can use this feature to: keep past versions of API descriptions for backwards compatibility, document experimental versions of software, or maintain release notes separate for each version.

To configure your project to include multiple versions, complete the following tasks:

1. Create version subfolders.
2. Add versioned content to the sidebar.
3. (Optional) Configure versions.yaml file.

Before you begin

Make sure you have the following before you begin:

• a redocly.yaml configuration file
• versioned content

Create version subfolders

To include versioned content with a version picker, you must organize your content into version subfolders.

To organize your content into version subfolders:

1. Create a main content folder.
2. Create subfolders for the different versions within the main content folder.
   Version subfolder names must start with the "@" symbol, but otherwise can be any string, with or without numbers. For example, @latest, @1.0.0, @rc1 are all valid.
   You can add as many version subfolders as you need, but nesting them is not supported.
3. Place the files for the different versions in their specified folders.

Examples of versioned content structures

The following example includes versions 1.0, 2.0, and 3.0 of the museum_api, and the legacy and latest versions of the customer_api:

my_awesome_docs
├── museum_api
│   ├── @1.0
│   │   ├── index.md
│   │   ├── museum.yaml
│   │   └── overview.md
│   ├── @2.0
│   │   ├── index.md
│   │   └── museum.yaml
│   └── @3.0
│       ├── diagram.png
│       ├── index.md
│       └── museum.yaml
├── customer_api
│   ├── @latest
│   │   ├── index.md
│   │   └── petstore.yaml
│   ├── @legacy
│   │   ├── index.md
│   │   ├── petstore.yaml
│   │   └── readme.md
│   └── versions.yaml
├── index.md
└── sidebars.yaml

The museum_api versions will appear in the version picker in the same order as the version subfolders in the file tree: 1.0, then 2.0, and finally 3.0. The version opened by default will be the the last version, in this case: 3.0.

Since in customer_api the legacy version appears second, it would also be the default version. To make the latest version appear at the bottom of the list and be the default version, a versions.yaml file with the desired configuration was added to the customer_api folder.

Another example shows the public beta version of payments_api:

my_awesome_docs
├── payments_api
│   └── @public_beta
│       ├── index.md
│       └── payments.yaml
├── index.md
└── sidebars.yaml

In this case payments_api contains only one version subfolder. This configuration is enough to enable the version picker which displays one available version: public_beta. You can use a similar structure to prepare your project for upcoming versions of content.

Add versioned content to the sidebar

After creating the structure for your versioned content, let's configure navigation for this structure. To display the version picker on your project page, configure a sidebar.

You can use the existing sidebars.yaml file, or create a new one. Depending on your design, you can place sidebars.yaml in the root directory of your project, or in the same folder as versioned content folders. For example, if you have your content split into several products, you might want to add links to versioned content only in the relevant product's sidebar.

To add versioned content folders to sidebars.yaml:

1. Create a sidebars.yaml file or open an existing one.
2. Add the page option with the path to each versioned file in each version subfolder as the value:
   sidebars.yaml

   - page: ./@latest/index.md
   - page: ./@latest/petstore.yaml 
   - page: ./@legacy/index.md 
   - page: ./@legacy/petstore.yaml
   - page: ./@legacy/readme.md
   

3. (Optional): you can customize the sidebar link labels with label and labelTranslationKey options.
   For example:
   sidebars.yaml

   - page: ./@latest/index.md
     label: Getting started with petstore 
   - page: ./@latest/petstore.yaml
     label: Petstore API
   - page: ./@legacy/index.md
     label: (legacy) Getting started with petstore 
   - page: ./@legacy/petstore.yaml
     label: (legacy) Petstore API 
   - page: ./@legacy/readme.md
   

   The external option does not apply to pages that have paths to version subfolders.

After you complete the configuration, Redocly adds a version picker to the sidebar of versioned content in your project.

Customize the version picker

By default, the order of versions is the same as the folder structure in the project: in the alphanumeric ascending order. The version that opens when you navigate to versioned file, is by default the version last in the order.
You can customize which versions appear in the version picker, the order of the versions, and the version that opens by default.

To specify the default version as well as choose which versions to display:

1. Create a versions.yaml file on the same level as your version subfolders.
2. In the file, add a default object with one of the version subfolder's name, without the @ sign, as the value.
   versions.yaml

   default: latest
   

3. Add a versions object, and inside it a map of version objects with version subfolder names as values.
   versions.yaml

   default: latest
   versions:
     - version: legacy
     - version: latest
   

   Note that the @ sign is omitted.
4. (Optional) You can provide a name option for each version.
   versions.yaml

    default: latest
    versions:
      - version: legacy
        name: Legacy version
      - version: latest
        name: Latest version
   

As an example, let's assume this file structure:

my_awesome_docs
└── customer_api
    ├── @latest
    │   ├── index.md
    │   └── petstore.yaml
    ├── @legacy
    |   ├── index.md
    |   ├── petstore.yaml
    |   └── readme.md
    ├── @demo
    │   ├── index.md
    │   └── petstore.yaml
    └── versions.yaml

In this example, we created a versions.yaml file with two versions: legacy and latest, specifying latest as the default. The demo version was purposefully not included.

default: latest
versions:
  - version: legacy
    name: Legacy version
  - version: latest
    name: Latest version

Add version picker to all content

You can configure your project to display the version picker on all pages, even those that do not have defined versions.

To display the version picker for all content use the following configuration in your redocly.yaml file:

versionPicker:
  showForUnversioned: true

For pages that do not have multiple version, the version picker is inactive and displays All versions.

Resources

• Reference the options for configuring which versions appear in the version picker, in what order, and which version is the default.
• Learn how to set up the sidebar in the Configure navigation on the sidebar how-to documentation.