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.

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:

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

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.

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.

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.

docuo version --create 1.1.0

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.

# The new file.
docs/new.md

# Edit the corresponding sidebar file.
docs/sidebars.json

# The new file.
versioned_docs/version-1.0.0/new.md

# Edit the corresponding sidebar file.
versioned_docs/version-1.0.0/sidebars.json

{
  "mySidebar": [
    {
      "type": "autogenerated",
      "dirName": "."
    }
  ]
}

{
  "mySidebar": [
    {
      "type": "doc",
      "id": "new",
      "label": "New"
    }
  ]
}

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

docuo version --delete 1.1.0

By manual configuration

1. Remove the version from versions.json. Example:

[
  "2.0.0",
  "1.9.0",
- "1.8.0"
]

2. Delete the versioned docs directory. Example: versioned_docs/version-1.8.0.

Recommended practices

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 😊

Link docs by file paths

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.

Check the `docuo.config.json` [**API reference**](../../customizing/customize-with-json-file.mdx) for an exhaustive list of options.

Versioned collocated assets

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

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