When your product ships a new major release, you may want the old docs to stay readable. Each docs version is its own collection under its own path: the current docs stay at /, and v1 lives in src/content/docs-v1/, served at /v1/.
Versions of a generated API reference work differently; see API versions.
Add a version
The new-version recipe sets up a version end to end: it copies the content, registers the collection, adds its route, records it in the Nimbus config, and installs the version picker in your header.
npx @cloudflare/nimbus-docs add new-versionyarn nimbus-docs add new-versionpnpm nimbus-docs add new-versionbunx @cloudflare/nimbus-docs add new-versionadd hands the recipe to your coding agent, which asks which version to create and whether it’s deprecated or hidden. To read the steps yourself, add --print.
The version manifest
The recipe records your versions in the Nimbus config in astro.config.ts:
const nimbusConfig = defineNimbusConfig({
// …
versions: {
current: "v3",
others: ["v2", "v1"],
deprecated: ["v1"],
},
});| Field | What it does |
|---|---|
current |
The label of the docs at the root, the docs collection. |
others |
The other versions, newest first. Each <slug> needs a collection named docs-<slug>, and is the first segment of its URLs. |
deprecated |
Versions shown with a deprecation banner and a sidebar badge, and ranked lower in search. |
hidden |
Versions left out of the picker and search. Their pages still load at their URLs. |
What readers get
- A version picker in the header that keeps the reader on the same page when the page exists in both versions.
- Each version’s own sidebar, built from its own folder.
- A per-version
llms.txt, so agents can read one version at a time.
To retire a version, remove it from others and delete its collection, folder and route, then redirect its URLs to the current docs.