Versioning

Versioning allows for the maintenance of multiple versions of the same documentation, which is crucial for supporting different SDK releases. This guide explains how to create versioned documentation in the docs platform.

Creating a Versioned Page

To create a versioned page:

1. Ensure the original page already exists.
2. Create a new file with the same name as the original, but append __v{VERSION} (two underscores) to the filename before the extension.

The version should follow one of these two formats:

• Major version only (for general version ranges): __v{MAJOR}.x
• Full semantic version (for specific versions): __v{MAJOR}.{MINOR}.{PATCH}

For example:

index.mdx (original)
index__v7.x.mdx (version 7.x.x)
index__v7.1.0.mdx (specific version 7.1.0)

Versioning Platform Includes

Pages in the platform-includes folder can be versioned using the same method. However, the root page referencing these includes must also be versioned.

File Structure Example

docs/
├── getting-started/
│   ├── index.mdx
│   └── index__v7.x.mdx
└── platform-includes/
    └── configuration/
        ├── example.mdx
        └── example__v7.x.mdx

Version Selection and User Experience

When multiple versions of a page exist:

1. A dropdown menu appears below the platform selector, displaying all available versions for the current file.

2. When a user selects a version:

• They are redirected to the chosen version of the page.
• A preference is stored in localStorage, specific to the current guide or platform.

3. An alert is displayed when viewing "non-latest" pages to inform users they're not on the most recent version.

4. If a user has a stored version preference:

• The app will perform a client-side redirect to this version whenever it's available for other pages.

This approach ensures users can easily navigate between versions and keep their version preference across the documentation.

Best Practices

1. Only add versioning to pages when necessary, to avoid content duplication and save build times.
2. Ensure all related content (including platform-includes) is versioned consistently.

Limitations and Considerations

• Versioning is only available for existing pages.
• The versioning system relies on the file naming convention, so it's important to follow the __v{VERSION} format precisely.

By following these guidelines, it's possible to effectively manage multiple versions of documentation, ensuring users can access the appropriate information for their specific version of the software or API.