This document explains the docs versioning system in the @docusaurus/plugin-content-docs plugin. Versioning allows documentation sites to maintain multiple versions of documentation content simultaneously, each with its own routes, sidebars, and configuration. This enables sites to provide documentation for different software releases while keeping all versions accessible.
For information about internationalization (i18n) of versioned content, see Internationalization. For deployment of versioned sites, see Deployment Options.
Docusaurus versions are represented by VersionMetadata objects that define the structure and configuration of each documentation version. The plugin can manage multiple versions concurrently, with each version maintaining its own content path, sidebar configuration, and routing.
Version Metadata Processing Pipeline
Sources: packages/docusaurus-plugin-content-docs/src/versions/version.ts1-30
Each VersionMetadata object contains the following key properties:
| Property | Description |
|---|---|
versionName | Identifier for the version (e.g., "current", "1.0.0") |
contentPath | Filesystem path to the version's content directory |
contentPathLocalized | Optional localized content path for i18n |
sidebarFilePath | Path to the version's sidebar configuration file |
routeBasePath | URL base path for the version's routes |
path | Full route path including baseUrl |
tagsPath | Route path for the version's tags pages |
editUrl | Base URL for edit links |
editUrlLocalized | Localized edit URL when applicable |
Sources: packages/docusaurus-plugin-content-docs/src/versions/version.ts27-30
The version loading process transforms configuration into rendered content through several stages:
Version Content Loading Sequence
Sources: packages/docusaurus-plugin-content-docs/src/versions/loadVersion.ts1-20
Versions are configured through multiple mechanisms:
includeCurrentVersion, disableVersioning, lastVersion, etc.versions plugin option.The VERSIONS_JSON_FILE constant defines the expected location of the versions manifest.
Sources: packages/docusaurus-plugin-content-docs/src/constants.ts22
Content for different versions is organized in separate directories following a conventional structure:
Directory Structure for Versioned Documentation
The plugin identifies version-specific paths using utility functions like getVersionDocsDirPath and getVersionSidebarsPath.
Sources: packages/docusaurus-plugin-content-docs/src/versions/files.ts27-56
The docs plugin extends the Docusaurus CLI with version management commands. The cliDocsVersionCommand handles the creation of new version snapshots.
CLI Version Command Data Flow
Sources: packages/docusaurus-plugin-content-docs/src/cli.ts57-162
Version names must pass several checks in validateVersionName:
/ or \) packages/docusaurus-plugin-content-docs/src/versions/validation.ts28-33. or .. packages/docusaurus-plugin-content-docs/src/versions/validation.ts35-39Sources: packages/docusaurus-plugin-content-docs/src/versions/validation.ts13-52
The DocsVersionDropdownNavbarItem packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx allows users to switch versions via the navbar.
DocsVersionDropdownNavbarItem Logic
Sources: packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx113-194
User version preferences are persisted using the browser's storage system via createStorageSlot.
Version Preference Persistence
Sources: packages/docusaurus-theme-common/src/utils/storageUtils.ts139-204
Routes are generated for each version, ensuring that the same docId can exist at different paths depending on the version context. Theme components like DocNavbarItem use useActiveDocContext to determine if the current route matches the specific version of a document.
Sources: packages/docusaurus-theme-classic/src/theme/NavbarItem/DocNavbarItem.tsx16-43
When switching versions, Docusaurus preserves the current URL search parameters and hash to maintain context (e.g., search queries or anchor links).
Sources: packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx122-140
The versioning system in Docusaurus provides:
docs:version CLI command captures documentation state packages/docusaurus-plugin-content-docs/src/cli.ts147-160versioned_docs and versioned_sidebars packages/docusaurus-plugin-content-docs/src/versions/files.ts27-56Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.