Skip to main content
Version: 0.10

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.

docusaurus.config.ts
lastVersion: 'current',
versions: {
current: {
label: '0.10',
path: '',
},
},
SettingEffect
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:

  1. copies docs/ → versioned_docs/version-0.10/
  2. copies sidebars.ts → versioned_sidebars/version-0.10-sidebars.json
  3. adds "0.10" to the top of versions.json

Then update the config:

docusaurus.config.ts
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:

VersionURL
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.

Decide which version is the default

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>/
BothBoth — there is no inheritance between versions
Versions do not inherit

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.

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'],
Old links will 404

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.