Versioning

Maintain multiple versions of documentation with version-prefixed URLs and a version switcher

zudo-doc supports maintaining multiple versions of your documentation side by side. When versioning is enabled, older (or pre-release) versions are served under version-prefixed URLs, and a version switcher appears in the layout for users to navigate between versions.

Overview

Versioning lets you:

• Keep the latest documentation at /docs/... as usual
• Serve older versions at /v/{version}/docs/...
• Show a version switcher so users can navigate between versions
• Display version banners to indicate outdated or unreleased content

Enabling Versioning

Versioning is disabled by default. To enable it, add a versions array in src/config/settings.ts:

export const settings = {
  // ...
  versions: [
    {
      slug: "1.0",
      label: "1.0.0",
      docsDir: "src/content/docs-v1",
      locales: {
        ja: { dir: "src/content/docs-v1-ja" },
      },
      banner: "unmaintained",
    },
  ],
};

Set versions to false (or omit it) to disable versioning:

versions: false,

Configuration Reference

Each version entry accepts the following properties:

Directory Structure

Each version’s content lives in its own directory. The latest (current) version uses the default docsDir, while older versions use the directories specified in their configuration:

src/content/
├── docs/                # Latest version (default)
├── docs-ja/             # Latest version — Japanese
├── docs-v1/             # Version 1.0 — English
├── docs-v1-ja/          # Version 1.0 — Japanese
├── docs-v0.9/           # Version 0.9 — English
└── docs-v0.9-ja/        # Version 0.9 — Japanese

URL Structure

The latest version is served at the default docs URL. Older versions use a /v/{slug}/ prefix:

• Latest: /docs/getting-started/introduction
• Version 1.0: /v/1.0/docs/getting-started/introduction
• Version 0.9: /v/0.9/docs/getting-started/introduction

With locales, the locale prefix comes after the version prefix:

• Latest (Japanese): /ja/docs/getting-started/introduction
• Version 1.0 (Japanese): /v/1.0/ja/docs/getting-started/introduction

Version Switcher

When one or more versions are configured, a version switcher automatically appears in both the header bar and the doc content area. It displays the current version label and provides links to switch between all available versions, including the latest.

The switcher preserves the current page slug when navigating between versions, so users land on the same topic in the selected version.

If a page does not exist in an older version, that version’s link is automatically disabled (greyed out and not clickable) instead of linking to a 404 page. This is determined at build time by scanning each version’s content directory.

The dropdown also includes an “All versions” link at the bottom, which navigates to the versions listing page.

Versions Listing Page

A dedicated versions page is automatically generated at /docs/versions/ (and /ja/docs/versions/ for Japanese). This page lists all configured versions with their labels, status badges, and documentation links — similar to Docusaurus’ versions page.

The page is auto-generated from the versions array in settings.ts. No manual maintenance is needed — adding or removing versions in the configuration automatically updates the listing page.

Version Banners

Each version can display a banner at the top of every page to inform users about the version’s status. Two banner types are available:

Unmaintained

banner: "unmaintained",

Shows a warning-styled banner indicating the user is viewing documentation for an older version, with a link to the latest version.

Unreleased

banner: "unreleased",

Shows an info-styled banner indicating the user is viewing documentation for an unreleased version, with a link to the latest stable version.

No Banner

banner: false,

Disables the banner for that version. This is the default when banner is omitted.

Multi-Locale Support

Each version can define its own locale directories, independent of the main locale configuration:

versions: [
  {
    slug: "1.0",
    label: "1.0.0",
    docsDir: "src/content/docs-v1",
    locales: {
      ja: { dir: "src/content/docs-v1-ja" },
    },
    banner: "unmaintained",
  },
],

For each version and locale combination, zudo-doc creates a separate content collection (e.g., docs-v-1.0-ja) and generates the corresponding page routes.

Creating a New Version

When you’re ready to archive the current documentation as a new version:

1. Copy the current content directory to a new versioned directory:

   cp -r src/content/docs src/content/docs-v2

2. Copy locale directories if applicable:

   cp -r src/content/docs-ja src/content/docs-v2-ja

3. Add the version to settings:

   versions: [
     {
       slug: "2.0",
       label: "2.0.0",
       docsDir: "src/content/docs-v2",
       locales: {
         ja: { dir: "src/content/docs-v2-ja" },
       },
       banner: "unmaintained",
     },
     // ...existing versions
   ],

4. Update the current docs — The files in src/content/docs/ now represent the latest version. Update them as needed for the new release.