Configuration Options
versionsConfig is the block defineVersionedConfig adds on top of a normal VitePress configuration. It controls where your versioned content lives, how the current version is labelled, and how versions are switched.
// .vitepress/config.ts
import { defineVersionedConfig } from '@viteplus/versions';
export default defineVersionedConfig({
title: 'My Documentation',
versionsConfig: {
current: 'v2.0.x',
sources: 'src',
archive: 'archive',
versionSwitcher: {
text: 'Switch Version',
includeCurrentVersion: true
}
}
});Options
| Option | Type | Purpose |
|---|---|---|
current | string | Label for the live version served at the root URL |
sources | string | Directory holding the current version's content |
archive | string | Directory whose subfolders are archived versions |
versionSwitcher | object or false | The version dropdown; false disables it |
hooks.rewritesHook | (source, version, locale) => string | Maps a content file to its final URL |
Every option has a default, listed under Defaults.
current
The label for the version served from sources. It appears at the root URL and is highlighted in the switcher.
current: 'v2.0.x' // or 'latest', 'v3', ...This is a display label, not a directory name — nothing on disk has to match it.
The label also works as a URL prefix. A link to /v2.0.x/guide/ sends the reader to /guide/ while v2.0.x is current, and keeps working once v2.0.x is archived, since the archive then serves that path itself. Link to the versioned URL from a README or a changelog, and the link always lands on the version it was written for.
TIP
The redirect is a one-line script in the page <head>. On a built site it runs on the 404.html that VitePress builds, so it needs a host that serves that page for unknown paths, as GitHub Pages, Netlify, Vercel and Cloudflare Pages do. It is left out when an archived version carries the same label as current, since every path under that label is then a real page.
sources
The directory holding the current version's content, relative to the docs root.
sources: 'src' // or 'latest', 'content', ...docs/
└── src/ ← sources
├── index.md
└── guide/archive
The directory whose subfolders are treated as archived versions. Each subfolder name becomes that version's URL prefix and its key in the per-version nav and sidebar maps.
archive: 'archive' // or 'versions', 'old', ...docs/
└── archive/ ← archive
├── v1.0.x/ → /v1.0.x/
└── v1.5.x/ → /v1.5.x/The directory is created for you, with a .gitkeep, if it does not exist.
Directory names never reach the URL
sources and archive are filesystem locations only. Whatever you name them, the current version is served at the root and archived versions at /<subfolder>/. With sources: 'latest' the home page is still /, not /latest/.
The version switcher builds its list from the archive subfolders plus current, so renaming either directory needs no further configuration.
hooks
See URL Path Rewrites for customizing how content files map to URLs.
versionSwitcher
See Version Switcher for the dropdown and the VersionSwitcher component.
Defaults
Anything you omit falls back to:
const defaultConfiguration = {
versionsConfig: {
current: 'latest',
sources: 'src',
archive: 'archive',
hooks: {
rewritesHook: rewritesHook
},
versionSwitcher: {
text: 'Switch Version',
includeCurrentVersion: true
}
}
};