Docs versions & archive
Every published docs version is registered. Archive hides a version from the public dropdown without ever deleting it; restore brings it back.
Every published docs version is registered. Archive hides a version from the public dropdown without ever deleting it; restore brings it back.
Every documentation version you publish is registered in a shared docs version registry. The public version dropdown your readers see is derived from that registry. You can archive a version — drop it from the dropdown — and restore it later, because archive never deletes anything. It's a recoverable status flip, the same model as product soft-delete.
The same registry powers both kinds of docs:
docs/ folder.
See Update product docs.docs-v* tag.
See Platform docs publishing.When a docs version is published, it's registered as an immutable release keyed by its tag:
docs-v*
version for platform docs). Re-publishing the same tag with the same content is
idempotent; re-publishing a tag with different content is rejected — a
published tag never changes underneath your readers.version number per scope, plus its commitSha,
publishedAt, page list, and source (github/ui for product docs, ci
for platform docs).Postgres is canonical. The public feed is a derived docs/{scope}/versions.json
in R2 that lists only the public releases, newest first, with a latest
pointer:
{
"latest": "v1.4.0",
"releases": [
{ "tag": "v1.4.0", "commitSha": "a7e304e", "publishedAt": "2026-06-24T17:40:11.000Z", "source": "github" },
{ "tag": "v1.3.0", "commitSha": "291e686", "publishedAt": "2026-06-12T09:02:44.000Z", "source": "github" }
]
}
Archived releases are simply absent from this feed — they stay in the registry but drop out of the dropdown.
Archiving flips a version's status to archived. The effect is immediate and
fully reversible:
versions.json.latest, the feed's latest advances to the newest
remaining public version.Reach for archive when a version is superseded, was published by mistake, or documents a release you no longer want readers to land on — without losing the ability to bring it back.
Restoring flips an archived version back to public. It reappears in the dropdown
and rejoins versions.json exactly as it was — same tag, same content, same
publishedAt. Because nothing was ever deleted, restore is lossless and can be
done at any time.
Archive and restore are operate actions over live serving state, not changes to your docs source. They flip which versions are visible — they never edit the docs content. To change what a version says, publish a new version instead.
The version registry is shared, so archive/restore work the same for whichever docs you own:
In both cases the operation is the same recoverable status flip described above: archive to hide a version from readers, restore to bring it back. The set of versions you can act on is every release ever registered for that scope — including archived ones — newest first.
Publishing a new version is a separate action from archiving an old one.
Pushing docs (product) or cutting a docs-v* tag (platform) registers a new
version; archiving only changes the visibility of an existing one. See
Apply & deploy for the publish/release lifecycle.