Versioning
Publish multiple versions of your documentation with a version switcher, versioned URLs, and deprecation banners.
Ship documentation for multiple product versions side by side. Readers pick a version from a dropdown in the doc-site header; each version gets its own URL space, its own search scope, and — for retired versions — a deprecation banner.
Multi-version docs need the Pro plan or higher. Below Pro, a build that finds a versioning block still succeeds, but it builds and deploys only the default version. No version switcher, no /{label}/ URLs, and no versions.json. The build log records a warning naming the skipped versions:
Version builds already queued when a workspace downgrades finish normally. The next build after that stops queuing them.
Configure versions
Declare your versions in syntext.json under versioning.versions:
Versioning is configured only in syntext.json — the dashboard has no separate versioning setting (Settings › General › Appearance points back to this file).
Version fields
| Field | Type | Description |
|---|---|---|
label | string | Required. The version name shown in the switcher and used as the URL prefix (e.g. v1). |
branch | string | Git branch to build this version from. |
tag | string | Git tag to build this version from. Takes precedence over branch. |
default | boolean | Marks the version served at the site root. Defaults to the first version in the list. |
deprecated | boolean | Shows a deprecated badge in the switcher and a warning banner when readers view this version. |
deprecationMessage | string | Custom banner text for a deprecated version. |
autoRedirectToLatest | boolean | Redirects (302) any request for this version to the same path on the default version — for versions you've fully retired. |
Each version resolves to a git ref with this precedence: tag > branch > label (the label is used as a branch name when neither is set).
Creating a version
The recommended workflow when shipping a new major version:
git branch v1 main && git push origin v1main — it remains the default (latest) version and is still served at the site rootsyntext.json on main:/{label}/ — no extra builds to trigger.Versioned builds always use the versioning config from your default branch, so old branches don't need their syntext.json updated. Fan-out requires a git-connected project; CLI-upload projects (stx deploy) can't build historical refs and only serve the uploaded version.
URLs
The default version is served at the site root — its URLs never change when you adopt versioning. Every other version lives under its label as a path prefix:
The version switcher
When two or more versions are configured, a version dropdown appears on every guide and API-reference page. On doc engine v1 it sits in the header next to your brand:
/v1/guides/webhooks switches to /guides/webhooks, not to the homepagedeprecationMessage (or a sensible default pointing readers at the latest version)On doc engine v2 the version control sits in the header — where depends on the header style. Its menu marks the version you're on Current and other deprecated versions Legacy, and a deprecated version's notice shows in the announcement bar at the top of the page.
With a single version (or no versioning block) no switcher is rendered.
Versioned search
Search results are scoped to the version being browsed. The search API accepts a version parameter that filters hits to that version's URL prefix, so readers on /v1/... never see v2 pages in their results.
Comparing versions
The API can diff two versions' page inventories — useful for "what changed in v2" pages:
Retention
The default version keeps the deploy it is serving plus its five most recent predecessors; every other version keeps its live deploy plus three. Older ones are removed after every production deploy. A deploy made within the last hour is never removed, so a build in flight is never disturbed.
Removing an old deploy never changes what readers see — and a rollback doesn't depend on old deploys either, because it rebuilds the target from its commit or retained source.
After adding or changing versioning, push to your default branch (or trigger a deploy) — the version manifest, switcher, and all versioned builds are rebuilt automatically.