/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog

Versioning

Publish multiple versions of your documentation with a version switcher, versioned URLs, and deprecation banners.

4 min read

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.

Note

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:

text
Multi-version docs require the Pro plan or higher (this workspace is on starter); building only the default version "v2" and skipping v1

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:

syntext.json
{
"name": "Acme Docs",
"versioning": {
"versions": [
{ "label": "v2", "branch": "main", "default": true },
{
"label": "v1",
"branch": "v1",
"deprecated": true,
"deprecationMessage": "v1 is deprecated and will sunset on March 1, 2027. Migrate to v2."
}
]
}
}

Versioning is configured only in syntext.json — the dashboard has no separate versioning setting (Settings › General › Appearance points back to this file).

Version fields

FieldTypeDescription
labelstringRequired. The version name shown in the switcher and used as the URL prefix (e.g. v1).
branchstringGit branch to build this version from.
tagstringGit tag to build this version from. Takes precedence over branch.
defaultbooleanMarks the version served at the site root. Defaults to the first version in the list.
deprecatedbooleanShows a deprecated badge in the switcher and a warning banner when readers view this version.
deprecationMessagestringCustom banner text for a deprecated version.
autoRedirectToLatestbooleanRedirects (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:

1.
Freeze the old docs — create a branch (or tag) from your default branch at the point you want to preserve: git branch v1 main && git push origin v1
2.
Keep writing on main — it remains the default (latest) version and is still served at the site root
3.
Declare both versions in syntext.json on main:
json
{
"versioning": {
"versions": [
{ "label": "v2", "default": true },
{ "label": "v1", "branch": "v1", "deprecated": true }
]
}
}
4.
Push to your default branch. After the production build deploys, Syntext automatically builds every non-default version from its own branch or tag and deploys it under /{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:

text
https://acme-docs.syntext.dev/getting-started ← v2 (default)
https://acme-docs.syntext.dev/v1/getting-started ← v1

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:

•
The default version is badged latest; deprecated versions are badged deprecated
•
Switching versions preserves your current page path — /v1/guides/webhooks switches to /guides/webhooks, not to the homepage
•
Viewing a deprecated version shows a banner below the header with your deprecationMessage (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.

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:

text
GET /v1/projects/{projectId}/versions/diff?from=v1&to=v2

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.

Note

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.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext