Versions

Keep separate documentation for each release: up to 20 versions per site on Free or 50 on Pro. Each version has its own pages, navigation, and search. Assets, redirects, domains, and settings are shared across the site.

Slugs and URLs

One version on each site is the default version. It serves from unprefixed URLs. Every other version serves under its slug.

Version slugs must match ^[a-z0-9][a-z0-9._-]*$, which allows the dotted forms teams actually use: 1.0, 2.4.1, v3, next, legacy.

Two collision rules are enforced when you create a version:

• The slug may not be one of the paths the serving router owns — assets, search, v1, robots.txt, and the rest of the reserved list — and may not be index or end in .md.
• The slug may not shadow a page URL that already exists in any version of the site. If some version has a page at /next or /next/anything, a version slug of next is rejected with 409, at creation and on a rename.

Imports also reject pages whose first path segment matches a version slug.

The default version

The first version created on a site becomes its default automatically. After that, you set it explicitly:

curl -s -X PATCH "$DOCSARY_API/v1/sites/acme" \
  -H "authorization: Bearer $DOCSARY_KEY" \
  -H "content-type: application/json" \
  -d '{"default_version":"1.0"}'

Requests using the default version’s prefix redirect to its clean URL: /1.0/guide/install becomes /guide/install with a 301. Query strings are preserved.

If you delete the default version, serving falls back to the first version by position. Set another default explicitly.

Promoting a release

The sequence to publish a new version without disturbing the current one:

# 1. create it — it is not the default, so it serves under its own prefix
curl -s -X POST "$DOCSARY_API/v1/sites/acme/versions" \
  -H "authorization: Bearer $DOCSARY_KEY" \
  -H "content-type: application/json" \
  -d '{"slug":"2.0","name":"2.0","position":0}'

# 2. push content into it — visible at /2.0/... while you review
node scripts/push.mjs ./docs --site acme --version 2.0 --prune

# 3. promote when ready
curl -s -X PATCH "$DOCSARY_API/v1/sites/acme" \
  -H "authorization: Bearer $DOCSARY_KEY" \
  -H "content-type: application/json" \
  -d '{"default_version":"2.0"}'

The new version is public at /2.0/ while you review it. It is excluded from llms-full.txt until it becomes the default.

After promotion, clean URLs serve 2.0; the previous default remains available under /1.0/ while you retain it.

What visitors see on an old version

Three things change on any non-default version.

A banner links to the matching current page, or the site root if that page no longer exists.

The canonical URL points to the matching current page when it exists, and to itself otherwise.

Search stays within the version being read. Readers can choose Search all versions to broaden the results; non-current results are labeled, and duplicate paths favor the current version.

A version switcher appears in the header as soon as a site has more than one version. Its order follows each version's position field, then slug. Selecting an entry goes to that version's root.

Versions and the machine-readable surfaces

Use version-specific Markdown URLs when an agent needs an older release.

Pruning

--prune on a push, or a prune key on an import call, deletes every page in that version that is not in the list you send:

node scripts/push.mjs ./docs --site acme --version 1.0 --prune

Without pruning, a push only adds or updates pages. A renamed file leaves the old page in place until you remove it.

Send the complete keep list only after every content chunk succeeds. Check the target version, export a backup, and stop other writers first. Prune deletions apply together; the preceding imports do not. See Prune.

Renaming a page is a prune plus a redirect. The prune removes the old path; the redirect keeps its inbound links working.

Deleting a version

curl -s -X DELETE "$DOCSARY_API/v1/sites/acme/versions/0.9" \
  -H "authorization: Bearer $DOCSARY_KEY"

This deletes the version, its pages, and its search entries. There is no undo; take an export first. Cached or downloaded copies may remain.

If the deleted version was the site's default, the site is left with no default version.