Versioning

This site is set up for multiple documentation versions but currently publishes one: 0.9. This page explains that arrangement and gives the runbook for adding the next version.

How it is wired today

There is no versioned_docs/ directory yet. Instead, the working copy in docs/ is version 0.9 — Docusaurus calls this the current version, and the config labels it and serves it from the root docs path:

docusaurus.config.ts

lastVersion: 'current',
versions: {
  current: {
    label: '0.9',
    path: '',
    badge: false,
  },
},

Setting	Effect
label: '0.9'	The version selector shows "0.9" instead of "Next"
path: ''	Pages serve from /docs/<id> with no version segment
lastVersion: 'current'	docs/ is the default version readers land on
badge: false	No version stamp on each page while there is only one

Why not snapshot 0.9 now?

Because a snapshot has a real cost and no present benefit. With a frozen versioned_docs/version-0.9/, every correction to the published docs would have to be made inside that directory — and the natural instinct is to edit docs/, which would silently change nothing readers can see. One version, one place to edit. The snapshot happens when there is genuinely something to preserve.

Cutting the next version

When 1.0 ships and 0.9 must stay available, run this once:

npm run docusaurus docs:version 0.9

That command:

1. copies docs/ → versioned_docs/version-0.9/
2. copies sidebars.ts → versioned_sidebars/version-0.9-sidebars.json
3. creates versions.json containing ["0.9"]

Then update the config:

docusaurus.config.ts

const CURRENT_VERSION_LABEL = '1.0'; // was '0.9'

At this point docs/ is version 1.0 and 0.9 is frozen. URLs land as follows:

Version	URL
1.0 (current, default)	/docs/intro
0.9 (frozen)	/docs/0.9/intro

The 0.9 links that were live before the cut keep working, because path: '' kept the version segment out of them — 0.9's content simply moves to a prefixed path while the unprefixed path now serves 1.0.

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.9' so readers keep getting 0.9 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)	versioned_docs/version-0.9/
Both	Both — 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.

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'],

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.