Versioning

Docs versioning is not the same problem as code versioning. Readers arrive from a Google result for a feature that no longer exists, so the rule is: old pages never disappear, they get archived.

The model

Path	Content	Rule
/	current docs, edited freely	always matches main
/v1/…	frozen snapshot of the 1.x docs	never edited after freezing
git tag docs-v1.9.0	the exact commit the snapshot came from	immutable

v1 is a folder: src/content/docs/v1/. The version switcher in the header maps /guides/queues/ ⇄ /v1/guides/queues/.

Freezing a generation

When you cut a major release:

git checkout -b docs/freeze-v1
pnpm docs:freeze -- 1.9
git commit -am "docs: freeze v1.9 snapshot"

The script copies the current docs into src/content/docs/v1/, rewrites absolute links to point inside /v1/, and prepends the archive banner to every page. Review the diff — the link rewrite is regex-based, so anything clever needs a human eye.

Then, and only then, edit main for the new major.

Why not a branch per version?

Branch-per-version looks tidy and rots fast: you cannot fix a typo in main without also patching three branches, and your CI has to build each one. A folder keeps every generation in one build, one deploy and one search index. The trade-off is that archived docs share the current theme, which is almost always what you want.

Single-version products

If you never break your public API, skip versioning entirely and keep a changelog page instead. Most docs sites need this far less than they think.