Version 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, the sidebar displays a version picker at the top. The version picker enables users to select which version of content to display. The sidebar reflects the changes in files and filenames when you switch between versions.

You can use this feature to keep past versions of API descriptions for backwards compatibility. You can also 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. (Optional) Customize the sidebar containing versioned content
3. (Optional) Customize the version picker

Make sure you have the following before you begin:

• two or more versions of content files

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.

After building your project, when you access versioned content, the sidebar displays the version picker, enabling you to switch between content versions.

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

├──cafe_api/
│   ├──@1.0/
│   │   ├──index.md
│   │   ├──cafe.yaml
│   │   └──overview.md
│   ├──@2.0/
│   │   ├──index.md
│   │   └──cafe.yaml
│   └──@3.0/
│       ├──images/
│       │   └──diagram.png
│       ├──index.md
│       ├──readme.md
│       └──cafe.yaml
├──customer_api/
│   ├──@latest/
│   │   ├──index.md
│   │   └──payments.yaml
│   ├──@legacy/
│   │   ├──index.md
│   │   ├──payments.yaml
│   │   └──readme.md
│   └──versions.yaml
├──index.md
└──sidebars.yaml

The cafe_api folder has no versions.yaml file, so its versions appear in the version picker sorted from newest to oldest. The order is 3.0, then 2.0, and finally 1.0. The version that opens by default is the first version in that order, in this case 3.0.

The sort is numeric-aware, so it orders 2.10 before 2.9 instead of after it. It orders versions that are not numeric, such as latest or legacy, in reverse alphabetical order. The sort does not follow semver precedence, so 1.0.0-rc.1 appears above 1.0.0 in the version picker. If your version folders use prerelease identifiers, add a versions.yaml file to pin the order.

The customer_api folder uses named versions, so the same sorting would put legacy first and open legacy by default. That folder has a versions.yaml file instead, which sets both the order of the versions and the default version. Its configuration keeps legacy at the top of the list, and opens latest by default. The sorting described above no longer applies to customer_api.

Another example shows the public beta version of payments_api:

├──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 that displays one available version: public_beta. You can use a similar structure to prepare your project for upcoming versions of content.

After creating the structure for your versioned content, you can create a custom sidebar configuration for this structure. Where you place sidebars.yaml depends on your preferences and the contents of your project. Place it in the root directory of your project, or in the same folder as versioned content folders. For example, if you have more than one collection of versioned content, you might want to create a separate sidebar for each collection.

For more information about customizing sidebars, see: Sidebar configuration.

When you switch between versions, the sidebar updates according to the content of version subfolders. Updates include sidebar item labels and the number of files in a version subfolder.

You can create a sidebar for versioned folders without further customizations. Add the entire parent folder of versioned content to a sidebars.yaml file. Using this method, any files you add or modify later, automatically update sidebar links when you build the project. The directory option sorts the links in the natural order.

To customize a sidebar using the directory option:

1. Add a directory option for each folder containing versioned content in your sidebars.yaml file, as in the following example:
   sidebars.yaml

   - page: index.md
     label: Main page
   - directory:
   - directory: 

2. As the values for the directory keys, add paths to the folders containing versioned content, as in the following example:
   sidebars.yaml

    - page: index.md
      label: Main page
    - directory: /cafe_api
    - directory: /customer_api

This configuration modifies the sidebar to include links to all content files in the cafe_api folder followed by files in customer_api. The sidebar uses the titles or the first headings of the files as labels.

You can control the sidebar with a single file that determines the order of the links and the labels. Create a sidebars.yaml file in the folder containing your version subfolders. Add links to the individual files inside the version subfolders.

To add a single sidebar for all version folders:

1. In your project create a sidebars.yaml file in a folder a that contains your versioned content, as in the following example:
   Sample file structure for multiple folders with versioned content and a single sidebars file

   ├──my-awesome-docs/
   │   ├──cafe_api/
   │   │   ├──@1.0/
   │   │   ├──@2.0/
   │   │   └──@3.0/
   │   └──customer_api/
   │        ├──@latest/
   │        └──@legacy/
   └──sidebars.yaml

2. Add a page option with the value of a file path for each content file in each version subfolder. Add the options in your sidebars.yaml file, as in the following example:
   sidebars.yaml

   - page: index.md
     label: Main page
   - page: /cafe_api/@1.0/index.md
   - page: /cafe_api/@1.0/cafe.yaml
   - page: /cafe_api/@1.0/overview.md
   - page: /cafe_api/@2.0/index.md
   - page: /cafe_api/@2.0/cafe.yaml
   - page: /cafe_api/@3.0/index.md
   - page: /cafe_api/@3.0/cafe.yaml
   - page: /cafe_api/@3.0/readme.md
   - page: /customer_api/@legacy/index.md
   - page: /customer_api/@legacy/payments.yaml
   - page: /customer_api/@legacy/readme.md
   - page: /customer_api/@latest/index.md
   - page: /customer_api/@latest/payments.yaml 

3. (Optional) You can arrange the page options into groups so that each group appears under a single label.
   sidebars.yaml

   - page: index.md
     label: Main page
   - group: Cafe API
     items:
       - page: /cafe_api/@1.0/index.md
       - page: /cafe_api/@1.0/cafe.yaml
       - page: /cafe_api/@1.0/overview.md
       - page: /cafe_api/@2.0/index.md
       - page: /cafe_api/@2.0/cafe.yaml
       - page: /cafe_api/@3.0/index.md
       - page: /cafe_api/@3.0/cafe.yaml
       - page: /cafe_api/@3.0/readme.md
   - group: Customer API
     items:
       - page: /customer_api/@legacy/index.md
       - page: /customer_api/@legacy/payments.yaml
       - page: /customer_api/@legacy/readme.md
       - page: /customer_api/@latest/index.md
       - page: /customer_api/@latest/payments.yaml 

This configuration modifies the sidebar by adding two groups, Cafe API and Customer API. Within each group are multiple versions of files. When you first access your project, the sidebar displays only the links to files from the versions: 3.0 and legacy respectively. These versions are the default versions, as they are the first in the version order. To set custom default versions, see Customize the version picker.

The sidebar at the root of your project can become overly long. To prevent that, maintain separate sidebars.yaml files for your versioned content in their respective folders. This approach can be especially useful when your content has a large number of versions.

To add a dedicated sidebars.yaml for each version folder:

1. Add a sidebars.yaml file to each folder containing versioned content in your project, as in the following example:
   Sample file structure for multiple folders with versioned content

   ├──cafe_api/
   │   ├──@1.0/
   │   │   ├──index.md
   │   │   ├──cafe.yaml
   │   │   └──overview.md
   │   ├──@2.0/
   │   │   ├──index.md
   │   │   └──cafe.yaml
   │   ├──@3.0/
   │   │   ├──images/
   │   │   │   └──diagram.png
   │   │   ├──index.md
   │   │   ├──readme.md
   │   │   └──cafe.yaml
   │   └──cafe.sidebars.yaml
   ├──customer_api/
   │   ├──@latest/
   │   │   ├──index.md
   │   │   └──payments.yaml
   │   ├──@legacy/
   │   │   ├──index.md
   │   │   ├──payments.yaml
   │   │   └──readme.md
   │   ├──versions.yaml
   │   └──customer.sidebars.yaml
   ├──index.md
   └──sidebars.yaml

2. Add a page option with a value of the file path for each content file in each version subfolder. Add the options in each sidebars.yaml file, as in the following example:
   cafe.sidebars.yaml

   - page: /@1.0/index.md
     label: Cafe API
   - page: /@1.0/cafe.yaml
   - page: /@1.0/overview.md
   - page: /@2.0/index.md
     label: Cafe API
   - page: /@2.0/cafe.yaml
   - page: /@3.0/index.md
     label: Cafe API
   - page: /@3.0/cafe.yaml
   - page: /@3.0/readme.md

3. In the sidebars.yaml file at the root of your project, add references to the sidebar files for versioned content, as in the following example:
   sidebars.yaml

   - page: index.md
     label: Main page
   - $ref: /cafe_api/cafe.sidebars.yaml
   - $ref: /customer_api/customer.sidebars.yaml

In the built project, the sidebar combines the referenced sidebars.yaml files and displays links to the default version of the content.

In a folder without a versions.yaml file, the version picker sorts versions from newest to oldest. The sort is numeric-aware, so it orders 2.10 before 2.9. When you navigate to a versioned file, the version that opens is the first version in the order (the newest one).

You can customize which versions appear in the version picker, the order of the versions, and the version that opens by default. To learn more about version picker configuration, see Versions configuration options section on this page.

To specify the default version and choose which versions to display, create a versions.yaml file on the same level as your version subfolders:

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

• default - The version displayed first when the page loads. Must match a version folder name (without the @ prefix)
• versions - Array of version objects specifying which versions to include and their display names
• version - Must match the version subfolder name (without the @ prefix)
• name - Display name shown in the version picker. If not provided, uses the folder name

If you don't provide a name, the version picker displays the version folder name (without @) instead. As an example, let's assume this file structure:

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

For this structure, 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

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.

To work with versioned content in your React pages, you can use Redocly's version management hooks usePageVersions and usePageActiveVersion. These hooks let you access the current version information and manage version-specific content in your components.

The usePageVersions hook returns an array of version objects with the following structure:

Example usage:

import { usePageVersions } from '@redocly/theme/core/hooks';

function VersionedPage() {
  const versions = usePageVersions();
  
  return (
    <div>
      {versions.map(version => (
        <div key={version.version}>
          {version.label} {version.active && '(Active)'}
        </div>
      ))}
    </div>
  );
}

The useActivePageVersion hook returns the currently active version identifier as a string, or undefined if no version is active.

Example usage:

import { useActivePageVersion } from '@redocly/theme/core/hooks';

function VersionedPage() {
  const activeVersion = useActivePageVersion();
  
  return (
    <div>
      <h1>Current Version: {activeVersion}</h1>
      {/* Version-specific content */}
    </div>
  );
}

You can specify the default version and which versions to include in your project. Create a versions.yaml file on the same level as your version folders.

The following are examples of versions.yaml files:

The following example contains two versions: v1.0, and v1.1. The version picker displays Version 1.0 and Version 1.1 as the labels for these versions. As v1.0 is the default version, when you navigate to your versioned content, your project displays files from @v1.0 version subfolder.

default: v1.0
versions:
  - version: v1.0
    name: Version 1.0
  - version: v1.1
    name: Version 1.1

The following example contains three versions: 1.0, 2.0, and 2.3. Since the names contain only numbers, the example wraps them in single quotation marks to match the required string type for these values. The version picker displays 1.0, 2.0, and 2.3. The default version is not defined in this file, so the project displays files from the last version subfolder listed. In this case, it is @2.3.

versions:
  - version: '1.0'
  - version: '2.0'
  - version: '2.3'

• Sidebar configuration - Configure navigation structures and sidebar organization for versioned content with detailed syntax and options reference