Documentation Versioning

Maintaining multiple versions of your documentation is critical for many different technical products. This page goes into the details of how versioning works in ReadMe, as well as several use cases.

🚧

Affected Sections

Only the Guides, Recipes, and Reference sections are impacted by versioning. Content for all other sections (Landing Page, Discussions, Changelog) will persist across versions.

Making a New Version

To create a new version, go to Versions in the left hand menu. Then click on the Add New Version button in the right top corner. Choose which version to fork from. This will create a copy of this version, you will not be able to pull the changes back to the version that was forked.

Version Options

Main Version

This is the version that your domain will direct to. Users can change to a different version by clicking the version dropdown selector.

❗️

It is not possible to merge two versions. If you want to make changes to both, you will need to do it manually!

Beta

Indicating that a version is a beta will add a badge next to a version in the version dropdown selector. It does not create a callout on the page or any other visible changes.

Public

Selecting this will make this available in the version dropdown selector and to anyone that can view your docs. If unselected, this version will only be visible to project admins.

Deprecated

Select this to mark older versions. In addition to seeing a "deprecated" badge next to the version in the version dropdown selector, users will also see a big red banner above the docs when visiting this deprecated version. Here's how it looks:

Displaying Version Dropdown

By default, we show the aforementioned version dropdown picker in the subnavigation bar. You can toggle to display or hide this under Appearance > Site Navigation.

Semver(-ish)

Our versioning is based on Semver, but is much more flexible than Semver in terms of the acceptable inputs. This means your versions can be as simple as v1.0, but as complex as v1.0-hello-this-is-a-version.

Reusable Content

Any Reusable Content created within one Version can only be used within that Version's documentation; it's not possible to define Reusable Content blocks that can be used across Versions within a single project.

If a new Version is created when forked from an existing Version, the new Version inherits all the Reusable Content blocks defined in the existing Version. However, the Reusable Content blocks in the new Version are completely independent from the old Version.

📘

Global Reusable Content

Projects on an Enterprise plan have the ability to define Global Reusable Content that can be used across Projects and Versions. See our Reusable Content for Enterprise Groups docs for more information!

Use Cases

There are lots of different scenarios where doc versioning might be useful — some are more obvious than others. The most obvious use case is for when your documentation version needs to match the versioning that might be taking place with your API or other technical product, and you need to maintain copies of your docs for each respective version.

Another use case is for bigger content restructuring or migrations, especially when these changes are more involved than simply updating a few pages (in which case we'd recommend Suggested Edits. You can fork a new version of your docs, do some major restructuring (e.g. reorganizing page categories, combining pages, deleting outdated content, etc.), and still have your old docs as your public-facing changes. And when you're ready to flip the switch over, it's as easy as renaming the versions and toggling a few version settings! We have a detailed example of this in our 2021 Migration Guide.