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.
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:
website
├── sidebars.json # sidebar for the current docs version
├── docs # docs directory for the current docs version
│ ├── foo
│ │ └── bar.md # https://mysite.com/docs/next/foo/bar
│ └── hello.md # https://mysite.com/docs/next/hello
├── versions.json # file to indicate what versions are available
├── versioned_docs
│ ├── version-1.1.0
│ │ ├── foo
│ │ │ └── bar.md # https://mysite.com/docs/foo/bar
│ │ └── hello.md
│ └── version-1.0.0
│ ├── foo
│ │ └── bar.md # https://mysite.com/docs/1.0.0/foo/bar
│ └── hello.md
├── versioned_sidebars
│ ├── version-1.1.0-sidebars.json
│ └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json
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.
Path | Version | URL |
---|---|---|
versioned_docs/version-1.0.0/hello.md | 1.0.0 | /docs/1.0.0/hello |
versioned_docs/version-1.1.0/hello.md | 1.1.0 (latest) | /docs/hello |
docs/hello.md | current | /docs/next/hello |
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
.
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
Tagging a new version
- First, make sure the current docs version (the
./docs
directory) is ready to be frozen. - Enter a new version number.
- npm
- Yarn
- pnpm
npm run docusaurus docs:version 1.1.0
yarn docusaurus docs:version 1.1.0
pnpm run docusaurus docs:version 1.1.0