Boltdocs Logo
GuidesIntegrationsAPIPluginsComponentsReleases

Versioning

Maintain multiple versions of your documentation side by side using folder conventions and the versions config key.

Versioning lets you keep multiple parallel editions of your documentation active at the same time — one for each major version of your project. Users can switch between them, and older versions remain accessible without any manual maintenance.

Quick StartLink

Step 1: Add versions to your configurationLink

ts
export default defineConfig({
  versions: {
    defaultVersion: 'v2',
    versions: [
      { label: 'v2 (latest)', path: 'v2' },
      { label: 'v1',          path: 'v1' },
    ],
  },
})

Step 2: Create version foldersLink

sh
mkdir docs/v2 docs/v1

Step 3: Add your versioned contentLink

text
docs/
├── v2/
│   ├── guide/
│   │   └── index.md    → /docs/v2/guide
│   └── api/
│       └── config.md   → /docs/v2/api/config
└── v1/
    └── guide/
        └── index.md    → /docs/v1/guide

Configuration ReferenceLink

BoltdocsVersionsConfigLink

PropertyTypeRequiredDescription
defaultVersionstring✓The version path considered current/default. Pages of this version don't necessarily require their own folder if you want them at the root.
prefixstring—A string prepended to each version's path inside docs/ (e.g. 'v' → folders become docs/v1/, docs/v2/).
versionsVersionConfig[]✓The ordered list of available versions. The first item appears first in the version selector.

VersionConfigLink

PropertyTypeRequiredDescription
labelstring✓Human-readable label for this version (e.g. 'v2 (latest)'). Displayed in the version selector UI.
pathstring✓The folder name in docs/ and URL segment for this version (e.g. 'v1').

Using a Folder PrefixLink

If you want all version folders to share a common prefix (e.g. docs/releases/v1/, docs/releases/v2/), configure the prefix option:

ts
export default defineConfig({
  versions: {
    defaultVersion: 'v2',
    prefix: 'releases/',
    versions: [
      { label: 'v2 (latest)', path: 'v2' },
      { label: 'v1',          path: 'v1' },
    ],
  },
})

This maps docs/releases/v2/guide.md → /docs/releases/v2/guide.

Combining Versioning with i18nLink

When both versioning and i18n are active, the folder hierarchy is always version first, then locale:

text
docs/
└── v2/
    ├── guide.md         → /docs/v2/guide      (default locale)
    └── es/
        └── guide.md     → /docs/v2/es/guide   (Spanish)
Order matters

The version segment always resolves before the locale segment. Place locale folders inside version folders, not the other way around. The inverse structure (docs/es/v2/) is not supported.

Versioned URLsLink

Given this configuration:

ts
versions: {
  defaultVersion: 'v2',
  versions: [
    { label: 'v2', path: 'v2' },
    { label: 'v1', path: 'v1' },
  ],
}

A file at docs/v1/guide/install.md resolves to /docs/v1/guide/install. A file at docs/v2/guide/install.md resolves to /docs/v2/guide/install.

The version selector in the default layout lets users jump between versions while staying on the equivalent page.

Jesús Alcalá
Last updated on October 18, 2026

Was this page helpful?