Document Versioning in Docusaurus

If you ship a library or API, your users might be on different versions. Docusaurus has built-in versioning that lets you freeze a snapshot of your docs whenever you release, so v1 users still find v1 docs.

How Versioning Works

Think of it as snapshots. Every time you "cut" a version, Docusaurus copies your current docs into a timestamped folder:

docs/ — Always the "next" (unreleased/development) version
versioned_docs/version-X.X/ — Frozen snapshots of previous versions
versioned_sidebars/version-X.X-sidebars.json — Sidebar configs for each version

my-docusaurus-site/ ├── docs/ # "Next" version (development) │ ├── intro.mdx │ └── api/ │ └── methods.mdx ├── versioned_docs/ │ ├── version-2.0/ # v2.0 snapshot │ │ ├── intro.mdx │ │ └── api/ │ │ └── methods.mdx │ └── version-1.0/ # v1.0 snapshot │ ├── intro.mdx │ └── api/ │ └── methods.mdx ├── versioned_sidebars/ │ ├── version-2.0-sidebars.json │ └── version-1.0-sidebars.json ├── versions.json # List of all versions ├── sidebars.js # Sidebar for "next" version └── docusaurus.config.js

Creating Versions

Your First Version

Ready to ship v1.0? One command:

bash example

npx docusaurus docs:version 1.0

This does three things:

Copies the entire docs/ folder to versioned_docs/version-1.0/
Copies sidebars.js to versioned_sidebars/version-1.0-sidebars.json
Adds "1.0" to the versions.json file

:::tip[When to Create a Version] Create a new version whenever you release a major or minor version of your software. Patch releases typically don't need new doc versions — just update the current version's docs. :::

Subsequent Versions

As your project grows:

bash example

# After releasing v2.0
npx docusaurus docs:version 2.0

# After releasing v3.0
npx docusaurus docs:version 3.0

versions.json tracks them all:

Example

[ "3.0", "2.0", "1.0" ]

:::note The first entry in versions.json is the "current" (latest stable) version. The docs/ folder is always the "next" (unreleased) version. :::

Version Dropdown

Docusaurus gives you a version switcher dropdown for the navbar:

Example

module.exports = { themeConfig: { navbar: { items: [ { type: 'doc', docId: 'intro', position: 'left', label: 'Docs', }, // highlight-start { type: 'docsVersionDropdown', position: 'right', dropdownActiveClassDisabled: true, dropdownItemsAfter: [ { type: 'html', value: '<hr style="margin: 0.3rem 0;">', }, { to: '/versions', label: 'All versions', }, ], }, // highlight-end ], }, }, };

Visual Result: A dropdown appears in the top-right navbar showing the current version (e.g., "3.0"). Clicking it reveals all available versions plus a link to the versions overview page. The active version is marked with a checkmark.

Customizing Version Labels

Example

module.exports = { presets: [ [ 'classic', { docs: { lastVersion: 'current', versions: { current: { label: '3.0 🚀', path: '', // Serve at /docs/ (no version prefix) badge: true, }, '2.0': { label: '2.0', path: '2.0', // Serve at /docs/2.0/ banner: 'unmaintained', }, '1.0': { label: '1.0 (Legacy)', path: '1.0', banner: 'unmaintained', }, }, }, }, ], ], };

Version Banners

Docusaurus automatically shows warning banners on older versions:

Banner Type	Display
`'none'`	No banner
`'unreleased'`	"This is unreleased documentation" (for `next`)
`'unmaintained'`	"This version is no longer maintained"

Visual Result: A yellow banner appears at the top of older version pages stating "This is documentation for version X.X, which is no longer actively maintained." with a link to the latest version.

Versioned Sidebars

Each version gets its own sidebar config. You can restructure navigation between versions if you need to:

Example

{ "docs": [ { "type": "category", "label": "Getting Started", "items": [ "intro", "installation", "quick-start" ] }, { "type": "category", "label": "API Reference", "items": [ "api/methods", "api/types", "api/errors" ] } ] }

:::caution[Editing Versioned Sidebars] The versioned sidebar files are JSON (not JavaScript). You can edit them directly, but be careful — errors in these files will break the build for that version. :::

Version-Specific Content

Conditional Content by Version

Build a component that shows content only for specific versions:

jsx title="src/components/VersionOnly.jsx" example

import React from 'react';
import { useDocsVersion } from '@docusaurus/theme-common/internal';

export function VersionOnly({ version, children }) {
  const { version: currentVersion } = useDocsVersion();
  if (currentVersion === version) {
    return <>{children}</>;
  }
  return null;
}

export function SinceVersion({ version, children }) {
  return (
    <div className="since-version">
      <span className="badge badge--info">Since v{version}</span>
      {children}
    </div>
  );
}

mdx title="docs/api/methods.mdx" example

import { SinceVersion } from '@site/src/components/VersionOnly';

## API Methods

### fetchData()

Retrieves data from the server.

<SinceVersion version="2.0">

### streamData()

Real-time data streaming with WebSocket fallback.

</SinceVersion>

Version-Specific Admonitions

Example

:::caution[Breaking Change in v3.0] The `fetchData()` method now returns a `Promise<Result>` instead of a raw `Promise<Response>`. Update your code:

// Before (v2.x) const response = await fetchData('/api/users'); const data = await response.json();

// After (v3.0+) const { data, error } = await fetchData('/api/users');

mdx example

:::

Maintaining Multiple Versions

Strategy 1: Edit in `docs/`, Backport When Needed

This is the recommended approach:

Make all changes in docs/ (the next/development version)
When a fix applies to older versions, manually copy it to versioned_docs/version-X.X/
Only backport critical fixes (typos, broken links, security notes)

Strategy 2: Minimal Versioned Docs

Only version pages that actually change between releases:

Example

docs: { // Only include specific paths in versioning onlyIncludeVersions: process.env.NODE_ENV === 'development' ? ['current', '2.0'] // Fewer versions in dev for speed : undefined, // All versions in production }

Deleting Old Versions

To remove a version you no longer want to host:

Delete the folder from versioned_docs/version-X.X/
Delete the sidebar file versioned_sidebars/version-X.X-sidebars.json
Remove the entry from versions.json

bash example

# Remove version 1.0
rm -rf versioned_docs/version-1.0
rm versioned_sidebars/version-1.0-sidebars.json
# Edit versions.json to remove "1.0"

Migration Between Versions

Creating a Migration Guide

mdx title="docs/migration/v2-to-v3.mdx" example

# Migration Guide: v2 to v3

## Breaking Changes

### 1. New Return Types

| Method | v2 Return | v3 Return |
|--------|-----------|-----------|
| `fetchData` | `Promise<Response>` | `Promise<Result>` |
| `subscribe` | `Subscription` | `AsyncIterator` |

### 2. Removed APIs

The following APIs have been removed in v3:

- ~~`legacyFetch()`~~ → Use `fetchData()` instead
- ~~`syncRequest()`~~ → Use `await fetchData()` instead

### 3. Configuration Changes

// v2 configuration module.exports = { // remove-next-line plugins: ['@docusaurus/plugin-legacy'], // add-next-line plugins: ['@docusaurus/plugin-modern'], };

mdx example

Linking Between Versions

Example

{/* Link to same page in a different version */} See the [v2.0 documentation](/docs/2.0/api/methods) for the previous behavior. {/* Link to migration guide */} Ready to upgrade? Follow our [migration guide](./migration/v2-to-v3.mdx).

Build Performance with Many Versions

:::caution[Build Time Warning] Each version multiplies your build time. A site with 100 docs pages and 5 versions builds 500 pages. Consider these optimizations: :::

Example

module.exports = { presets: [ [ 'classic', { docs: { // Only build recent versions in development onlyIncludeVersions: process.env.NODE_ENV === 'development' ? ['current'] : undefined, // Disable "next" version in production if not needed includeCurrentVersion: process.env.NODE_ENV === 'development', }, }, ], ], };

Best Practices for Versioning

:::tip[Versioning Tips]

Version sparingly — Only create versions for major/minor releases
Keep docs/ clean — It represents your upcoming release
Use banners — Help users know when they're viewing old docs
Limit active versions — Maintain 2-3 versions max; archive the rest
Automate with CI — Create versions as part of your release pipeline
Document migrations — Every version should have a migration guide
Test all versions — Include older versions in your CI build checks

:::

Versioning keeps your docs useful to everyone, regardless of which release they're on. Just don't go overboard — maintaining too many versions gets painful fast. Keep 2-3 active, archive the rest, and always provide migration guides.

How Versioning Works

Think of it as snapshots. Every time you "cut" a version, Docusaurus copies your current docs into a timestamped folder:

docs/ — Always the "next" (unreleased/development) version
versioned_docs/version-X.X/ — Frozen snapshots of previous versions
versioned_sidebars/version-X.X-sidebars.json — Sidebar configs for each version

Creating Versions

Your First Version

Ready to ship v1.0? One command:

bash example

npx docusaurus docs:version 1.0

This does three things:

Copies the entire docs/ folder to versioned_docs/version-1.0/
Copies sidebars.js to versioned_sidebars/version-1.0-sidebars.json
Adds "1.0" to the versions.json file

Subsequent Versions

As your project grows:

bash example

# After releasing v2.0
npx docusaurus docs:version 2.0

# After releasing v3.0
npx docusaurus docs:version 3.0

versions.json tracks them all:

Example

[ "3.0", "2.0", "1.0" ]

:::note The first entry in versions.json is the "current" (latest stable) version. The docs/ folder is always the "next" (unreleased) version. :::

Version Dropdown

Docusaurus gives you a version switcher dropdown for the navbar:

Example

Visual Result: A dropdown appears in the top-right navbar showing the current version (e.g., "3.0"). Clicking it reveals all available versions plus a link to the versions overview page. The active version is marked with a checkmark.

Customizing Version Labels

Example

Version Banners

Docusaurus automatically shows warning banners on older versions:

Banner Type	Display
`'none'`	No banner
`'unreleased'`	"This is unreleased documentation" (for `next`)
`'unmaintained'`	"This version is no longer maintained"

Visual Result: A yellow banner appears at the top of older version pages stating "This is documentation for version X.X, which is no longer actively maintained." with a link to the latest version.

Versioned Sidebars

Each version gets its own sidebar config. You can restructure navigation between versions if you need to:

Example

Version-Specific Content

Conditional Content by Version

Build a component that shows content only for specific versions:

jsx title="src/components/VersionOnly.jsx" example

import React from 'react';
import { useDocsVersion } from '@docusaurus/theme-common/internal';

export function VersionOnly({ version, children }) {
  const { version: currentVersion } = useDocsVersion();
  if (currentVersion === version) {
    return <>{children}</>;
  }
  return null;
}

export function SinceVersion({ version, children }) {
  return (
    <div className="since-version">
      <span className="badge badge--info">Since v{version}</span>
      {children}
    </div>
  );
}

mdx title="docs/api/methods.mdx" example

import { SinceVersion } from '@site/src/components/VersionOnly';

## API Methods

### fetchData()

Retrieves data from the server.

<SinceVersion version="2.0">

### streamData()

Real-time data streaming with WebSocket fallback.

</SinceVersion>

Version-Specific Admonitions

Example

:::caution[Breaking Change in v3.0] The `fetchData()` method now returns a `Promise<Result>` instead of a raw `Promise<Response>`. Update your code:

// Before (v2.x) const response = await fetchData('/api/users'); const data = await response.json();

// After (v3.0+) const { data, error } = await fetchData('/api/users');

mdx example

:::

Maintaining Multiple Versions

Strategy 1: Edit in `docs/`, Backport When Needed

This is the recommended approach:

Make all changes in docs/ (the next/development version)
When a fix applies to older versions, manually copy it to versioned_docs/version-X.X/
Only backport critical fixes (typos, broken links, security notes)

Strategy 2: Minimal Versioned Docs

Only version pages that actually change between releases:

Example

Deleting Old Versions

To remove a version you no longer want to host:

Delete the folder from versioned_docs/version-X.X/
Delete the sidebar file versioned_sidebars/version-X.X-sidebars.json
Remove the entry from versions.json

bash example

# Remove version 1.0
rm -rf versioned_docs/version-1.0
rm versioned_sidebars/version-1.0-sidebars.json
# Edit versions.json to remove "1.0"

Migration Between Versions

Creating a Migration Guide

mdx title="docs/migration/v2-to-v3.mdx" example

# Migration Guide: v2 to v3

## Breaking Changes

### 1. New Return Types

| Method | v2 Return | v3 Return |
|--------|-----------|-----------|
| `fetchData` | `Promise<Response>` | `Promise<Result>` |
| `subscribe` | `Subscription` | `AsyncIterator` |

### 2. Removed APIs

The following APIs have been removed in v3:

- ~~`legacyFetch()`~~ → Use `fetchData()` instead
- ~~`syncRequest()`~~ → Use `await fetchData()` instead

### 3. Configuration Changes

// v2 configuration module.exports = { // remove-next-line plugins: ['@docusaurus/plugin-legacy'], // add-next-line plugins: ['@docusaurus/plugin-modern'], };

mdx example

Linking Between Versions

Example

Build Performance with Many Versions

:::caution[Build Time Warning] Each version multiplies your build time. A site with 100 docs pages and 5 versions builds 500 pages. Consider these optimizations: :::

Example

Best Practices for Versioning

:::tip[Versioning Tips]

Version sparingly — Only create versions for major/minor releases
Keep docs/ clean — It represents your upcoming release
Use banners — Help users know when they're viewing old docs
Limit active versions — Maintain 2-3 versions max; archive the rest
Automate with CI — Create versions as part of your release pipeline
Document migrations — Every version should have a migration guide
Test all versions — Include older versions in your CI build checks

:::

How Versioning Works

Creating Versions

Your First Version

Subsequent Versions

Version Dropdown

Customizing Version Labels

Version Banners

Versioned Sidebars

Version-Specific Content

Conditional Content by Version

Version-Specific Admonitions

Maintaining Multiple Versions

Strategy 1: Edit in docs/, Backport When Needed

Strategy 2: Minimal Versioned Docs

Deleting Old Versions

Migration Between Versions

Creating a Migration Guide

Linking Between Versions

Build Performance with Many Versions

Best Practices for Versioning

How Versioning Works

Creating Versions

Your First Version

Subsequent Versions

Version Dropdown

Customizing Version Labels

Version Banners

Versioned Sidebars

Version-Specific Content

Conditional Content by Version

Version-Specific Admonitions

Maintaining Multiple Versions

Strategy 1: Edit in docs/, Backport When Needed

Strategy 2: Minimal Versioned Docs

Deleting Old Versions

Migration Between Versions

Creating a Migration Guide

Linking Between Versions

Build Performance with Many Versions

Best Practices for Versioning

Strategy 1: Edit in `docs/`, Backport When Needed

Strategy 1: Edit in `docs/`, Backport When Needed