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

# 多版本

Rspress 的默认主题中支持多版本文档管理，接下来，我们将介绍如何接入多版本文档。

## `multiVersion` 配置

通过 `multiVersion` 配置版本列表和默认版本，比如：

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

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

其中，`default` 为默认版本，`versions` 为版本列表。

## 添加多版本文档

根据你配置的版本列表，在 `docs` 目录下，添加多版本文档，比如：

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

在 Rspress 的约定式路由中，对于默认版本，会自动省略掉版本的路径前缀。如 `v1/index.mdx` 会被渲染为 `/` 路由，而 `v2/index.mdx` 会被渲染为 `/v2/` 路由。

:::tip 提示

对于文档中的链接，你不需要手动添加版本前缀，Rspress 会自动根据当前文档的版本，添加对应的版本前缀。如 `v2/index.mdx` 中的链接 `/guide/` 会被渲染为 `/v2/guide/`。

:::

## 配合国际化使用

多版本文档可以和[国际化](https://rspress.rs/zh/guide/basic/i18n.md)一起使用。同时开启时，目录结构以**版本为顶层目录，语言为子目录**：

```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'],
  },
});
```

文档目录结构如下：

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

生成的路由遵循 `/{version}/{lang}/` 的规则：

| 文件路径             | 路由                       |
| ---------------- | ------------------------ |
| `v1/en/index.md` | `/`（默认版本 + 默认语言，两个前缀均省略） |
| `v1/zh/index.md` | `/zh/`                   |
| `v2/en/index.md` | `/v2/`                   |
| `v2/zh/index.md` | `/v2/zh/`                |

## 组件中获取当前版本

在组件中，你可以通过 [`useVersion`](https://rspress.rs/zh/ui/hooks/use-version.md) 获取当前版本，比如：

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

export default () => {
  const version = useVersion();
  return <div>当前版本：{version}</div>;
};
```

## 按版本搜索

默认情况下，`search.versioned` 为 `true`，即搜索仅会查询当前所选版本对应的索引。如果你希望跨版本搜索，可以将其设置为 `false`：

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

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