Versioning
This site publishes two documentation versions: 0.10, the one being written, and 0.9, frozen on 2026-11-16. This page explains the arrangement and gives the runbook for adding the next version.
How it is wired today
The working copy in docs/ is version 0.10. Docusaurus calls it the current
version, and the config labels it and serves it from the root docs path. 0.9 lives
in versioned_docs/version-0.9/, with its sidebar in
versioned_sidebars/version-0.9-sidebars.json, and versions.json lists it.
lastVersion: 'current',
versions: {
current: {
label: '0.10',
path: '',
},
},
| Setting | Effect |
|---|---|
label: '0.10' | The version selector shows "0.10" instead of "Next" |
path: '' | 0.10 pages serve from /docs/<id> with no version segment |
lastVersion: 'current' | docs/ is the default version readers land on |
0.9 pages serve from /docs/0.9/<id>, and every page carries a version badge now
that there is more than one.
Cutting the next version
When the next version ships and 0.10 must stay available, run this once:
npm run docusaurus docs:version 0.10
That command:
- copies
docs/→versioned_docs/version-0.10/ - copies
sidebars.ts→versioned_sidebars/version-0.10-sidebars.json - adds
"0.10"to the top ofversions.json
Then update the config:
const CURRENT_VERSION_LABEL = '1.0'; // was '0.10'
At this point docs/ is version 1.0 and 0.10 is frozen alongside 0.9. URLs land as follows:
| Version | URL |
|---|---|
| 1.0 (current, default) | /docs/intro |
| 0.10 (frozen) | /docs/0.10/intro |
| 0.9 (frozen) | /docs/0.9/intro |
Unprefixed links keep working across the cut, because path: '' keeps the version
segment out of them: they now serve 1.0, and 0.10's content moves to a prefixed path.
Leaving lastVersion: 'current' publishes 1.0 as the default the moment you cut.
If 1.0 is still being written, set lastVersion: '0.10' so readers keep getting
0.10 until 1.0 is ready, and 1.0 becomes reachable as the unreleased version.
After the cut: where to edit
This is the part that catches people out.
| Editing… | Change files in… |
|---|---|
| The version being written (1.0) | docs/ |
| A published older version (0.9, 0.10) | versioned_docs/version-<version>/ |
| Both | Both — there is no inheritance between versions |
A fix applied only to docs/ will never appear in 0.9, and vice versa. When you
fix something that was also wrong in an older version, apply it to each version
you still support.
Sidebars are versioned too
The sidebar is declared explicitly in sidebars.ts rather than autogenerated,
precisely because it gets snapshotted per version. Each frozen version keeps the
table of contents it shipped with, in
versioned_sidebars/version-<v>-sidebars.json.
The consequence: adding a page means adding it to the sidebar too. An autogenerated sidebar would re-derive itself from the filesystem, which is the opposite of what a frozen version wants.
Retiring a version
To stop publishing a version, remove its entry from versions.json and delete
its versioned_docs/ and versioned_sidebars/ files.
To keep publishing it but hide it from the selector, list only the versions you want in the config:
onlyIncludeVersions: ['current', '1.0'],
Retiring a version removes its pages. If they were ever public, add redirects
(@docusaurus/plugin-client-redirects) rather than letting them break.
Release notes are not versioned
The release notes are chronological, not versioned — one entry
per release, always all visible. They are a blog in Docusaurus terms, configured
under release-notes/. Documentation versions and release-note entries are
independent: cutting a docs version does not create a release-note entry, and
vice versa.