logo
On this page

Docs versioning

You can use the versioning CLI to create a new documentation version based on the latest content in the docs directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs directory continues to evolve.

WARNING

Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!

Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation.

To better understand how versioning works and see if it suits your needs, you can read on below.

Overview

A typical versioned doc site looks like below:

Untitled
website
├── docs                            # docs directory for the current docs version
│   ├── Overview
│   │   └── Introduction.md         # https://mysite.com/docs/next/overview/introduction
│   └── hello.md                    # https://mysite.com/docs/next/hello
│   └── sidebars.json               # sidebar for the current docs version
├── versions.json                   # file to indicate what versions are available
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── Overview
│   │   │   └── Introduction.md     # https://mysite.com/docs/overview/introduction
│   │   │── hello.md                # https://mysite.com/docs/hello
│   │   └── sidebars.json           # sidebar for the current docs version
│   └── version-1.0.0
│       ├── Overview
│       │   └── Introduction.md     # https://mysite.com/docs/1.0.0/overview/introduction
│       │── hello.md                # https://mysite.com/docs/1.0.0/hello
│       └── sidebars.json           # sidebar for the current docs version
└── docuo.config.json               # website base config
1
Copied!

The versions.json file is a list of version names, ordered from newest to oldest.

The table below explains how a versioned file maps to its version and the generated URL.

PathVersionURL
versioned_docs/version-1.0.0/hello.md1.0.0/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md1.1.0 (latest)/docs/hello
docs/hello.mdcurrent/docs/next/hello
TIP

The files in the docs directory belong to the current docs version.

By default, the current docs version is labeled as Next and hosted under /docs/next/*, but it is entirely configurable to fit your project's release lifecycle.

Terminology

Note the terminology we use here.

Current version: The version placed in the ./docs folder.

Latest version / last version: The version served by default for docs navbar items. Usually has path /docs.

NOTE

Current version is defined by the file system location, while latest version is defined by the the navigation behavior. They may or may not be the same version! (And the default configuration, as shown in the table above, would treat them as different: current version at /docs/next and latest at /docs.)

Tutorials

Create a new version

  1. First, make sure the current docs version (the ./docs directory) is ready to be frozen.
  2. Enter a new version number.
Untitled
docuo version --create 1.1.0
1
Copied!

When tagging a new version, the document versioning mechanism will:

  • Copy the full docs/ folder contents into a new versioned_docs/version-[versionName]/ folder.
  • Append the new version number to versions.json.

Creating new docs

  1. Place the new file into the corresponding version folder.
  2. Include the reference to the new file in the corresponding sidebar file according to the version number.
Current
Older
# The new file.
docs/new.md

# Edit the corresponding sidebar file.
docs/sidebars.json
1
Copied!
# The new file.
versioned_docs/version-1.0.0/new.md

# Edit the corresponding sidebar file.
versioned_docs/version-1.0.0/sidebars.json
1
Copied!
TIP

Versioned sidebar files are, like standard sidebar files, relative to the content root for the given version — so for the example above, your versioned sidebar file may look like:

Untitled
{
  "mySidebar": [
    {
      "type": "autogenerated",
      "dirName": "."
    }
  ]
}
1
Copied!

or for a manual sidebar:

Untitled
{
  "mySidebar": [
    {
      "type": "doc",
      "id": "new",
      "label": "New"
    }
  ]
}
1
Copied!

Updating an existing version

You can update multiple docs versions at the same time because each directory in versioned_docs/ represents specific routes when published.

  1. Edit any file.
  2. Commit and push changes.
  3. It will be published to the version.

Example: When you change any file in versioned_docs/version-2.6/, it will only affect the docs for version 2.6.

Deleting an existing version

You can delete/remove versions as well in the following two ways.

Using the command line

Untitled
docuo version --delete 1.1.0
1
Copied!

By manual configuration

  1. Remove the version from versions.json. Example:
Untitled
[
  "2.0.0",
  "1.9.0",
- "1.8.0"
]
1
Copied!
  1. Delete the versioned docs directory. Example: versioned_docs/version-1.8.0.

Version your documentation only when needed

For example, you are building documentation for your Overview doc and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.

Should you cut a new documentation version 1.0.1? You probably shouldn't. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files.

Keep the number of versions small

As a good rule of thumb, try to keep the number of your versions below 10. You will very likely to have a lot of obsolete versioned documentation that nobody even reads anymore. For example, Jest is currently in version 27.4, and only maintains several latest documentation versions with the lowest being 25.X. Keep it small 😊

TIP

ARCHIVE OLDER VERSIONS If you deploy your site on a Jamstack provider (e.g. Netlify), the provider will save each production build as a snapshot under an immutable URL. You can include archived versions that will never be rebuilt as external links to these immutable URLs. The Jest website and the Docuo website both use such pattern to keep the number of actively built versions low.

Refer to other docs by relative file paths with the .md or .mdx extension, so that Docuo can rewrite them to actual URL paths during building. Files will be linked to the correct corresponding version.

Untitled
Check the `docuo.config.json` [**API reference**](../../Customizing/Customize%20with%20json%20file.mdx) for an exhaustive list of options.
1
Copied!
TIP

If the path contains Spaces, it must be escaped to '%20' first.

Versioned collocated assets

Put your assets in the docs version, and use relative paths:

Untitled
![img alt](../../docs_image/banner_api.png)
1
Copied!