Documentation versioning#

View Markdown

When versions is enabled, the SSG can keep a live docs tree next to frozen snapshots and render a header version dropdown.

The feature is off unless you turn it on. Existing sites stay unchanged. Versioning duplicates content on disk. Historical snapshot directories are read during the build and are never rewritten.

import { oxContent } from "@ox-content/vite-plugin";

export default {
  plugins: [
    oxContent({
      versions: {
        current: "3.0.0-alpha",
        entries: [
          {
            id: "3.0.0-alpha",
            label: "3.0.0-alpha",
            prefix: "",
            banner: "unreleased",
          },
          {
            id: "2.90.0",
            label: "2.90.0",
            prefix: "2.90",
            dir: "versions/2.90",
          },
        ],
      },
    }),
  ],
};

false or omitted keeps prefixes, banners, and the dropdown off. true enables a single current entry labeled Latest. An object enables the feature and overrides only the fields you set.

Option	Type	Default
`versions`	`boolean` / `VersionsOptions`	`false`
`current`	`string`	first entry, or `"current"`
`switcher`	`boolean`	`true`
`badge`	`boolean`	`true`
`entries`	`VersionEntry[]`	one current `Latest` entry

Each entry may set:

Field	Purpose
`id`	Stable key referenced by `current`
`label`	Dropdown text (HTML-escaped)
`prefix`	URL segment such as `2.90` or `next`. Empty string is the site root
`dir`	Snapshot directory relative to the Vite root. Omit for the live `srcDir`
`banner`	`"unreleased"`, `"unmaintained"`, or omitted

Search on a prefixed tree fetches {prefix}/search-index.json instead of the root index. Sitemaps stay scoped to the live tree unless a snapshot pass writes its own files. javascript:, data:, vbscript:, //, and .. prefixes or snapshot paths are dropped.

Inside a frozen snapshot, safe internal sidebar and header links stay under that snapshot's prefix. This includes generated and manual sidebars, nested items, permalinks, frontmatter aliases, configured redirects, breadcrumb roots, and previous/next links. Locale resolution runs first, so a link from /2.90/ja/ keeps both the 2.90 version and ja locale when the translated sibling exists.

If a sidebar destination does not exist in the snapshot, ox-content links to that version's root (for example, /2.90/) instead of silently returning to the live docs. External URLs, mailto:, hash-only links, unsafe schemes, and protocol-relative URLs are never version-prefixed. The live tree keeps its existing unprefixed navigation.

Recreate a snapshot from a git tag with:

node tools/scripts/snapshot-docs-version.mjs --tag v2.90.0 --prefix 2.90

Documentation versioning#

Related#