#Multi-version

Rspress's default theme supports multi-version docs. This guide shows how to enable and organize them.

#multiVersion config

Configure the version list and default version with multiVersion:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});

Here, default is the default version, and versions is the version list.

#Add multi-version docs

Based on the configured version list, add versioned docs under the docs directory:

In Rspress conventional routing, the version path prefix is omitted for the default version. For example, v1/index.mdx is rendered as /, while v2/index.mdx is rendered as /v2/.

#Using with i18n

You can use multi-version docs together with internationalization. When both are enabled, the directory structure uses versions at the top level, then language subdirectories within each version:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  lang: 'en',
  locales: [
    {
      lang: 'en',
      label: 'English',
    },
    {
      lang: 'zh',
      label: '简体中文',
    },
  ],
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});

Organize the docs directory as follows:

The generated routes follow the pattern /{version}/{lang}/:

#Get the current version in components

In components, get the current version with useVersion:

import { useVersion } from '@rspress/core/runtime';

export default () => {
  const version = useVersion();
  return <div>Current version: {version}</div>;
};

#Version-specific search

By default, search.versioned is true, which means the search will only query the index corresponding to the currently selected version. If you want to search across all versions, you can set it to false:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
  search: {
    versioned: false,
  },
});