> For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt.

# 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`:

```ts title="rspress.config.ts"
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:

```tree
docs
├── v1
│   ├── index.mdx
│   └── guide
│       └── index.mdx
└── v2
    ├── index.mdx
    └── guide
        └── index.mdx
```

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/`.

:::tip Tip

For document links, you do not need to manually add the version prefix. Rspress adds the corresponding prefix based on the current document version. For example, `/guide/` in `v2/index.mdx` is rendered as `/v2/guide/`.

:::

## Using with i18n

You can use multi-version docs together with [internationalization](https://rspress.rs/guide/basic/i18n.md). When both are enabled, the directory structure uses **versions at the top level, then language subdirectories** within each version:

```ts title="rspress.config.ts"
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:

```tree
docs
├── v1
│   ├── en
│   │   ├── _nav.json
│   │   ├── index.md
│   │   └── guide
│   │       └── index.md
│   └── zh
│       ├── _nav.json
│       ├── index.md
│       └── guide
│           └── index.md
└── v2
    ├── en
    │   ├── _nav.json
    │   ├── index.md
    │   └── guide
    │       └── index.md
    └── zh
        ├── _nav.json
        ├── index.md
        └── guide
            └── index.md
```

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

| File path        | Route                                                           |
| ---------------- | --------------------------------------------------------------- |
| `v1/en/index.md` | `/` (default version + default language, both prefixes omitted) |
| `v1/zh/index.md` | `/zh/`                                                          |
| `v2/en/index.md` | `/v2/`                                                          |
| `v2/zh/index.md` | `/v2/zh/`                                                       |

## Get the current version in components

In components, get the current version with [`useVersion`](https://rspress.rs/ui/hooks/use-version.md):

```tsx
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`:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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