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 Guides, Recipes, and Reference sections are versioned. Content for Landing Page, Discussions, and Changelog will persist across versions.

Making a New Version

To create a new version, open the Versions & Branches menu by selecting the version name (i.e. v3.0) in the admin navigation. Then click on the + New Version button in the right top corner. Choose which version to fork from and name your new version. This will create a copy of this version, you will not be able to pull the changes back to the version that was forked.

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.

---

Version Options

Default

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!

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 be marked as Hidden and only be visible to project admins.

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.

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 in Settings > Header & Footer > Subnavigation.

---

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!

---

FAQ

How many versions can I create?

Free plan users can create up to 3 versions. Upgrade to the Startup plan or higher to unlock unlimited versions.