close
Rspress
  • 中文

      • 多版本文档

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

      multiVersion 配置

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

      rspress.config.ts
      import { defineConfig } from '@rspress/core';

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

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

      添加多版本文档

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

      docs
      v1
      index.mdx
      guide
      index.mdx
      v2
      index.mdx
      guide
      index.mdx

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

      提示

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

      配合国际化使用

      多版本文档可以和国际化一起使用。同时开启时，目录结构以版本为顶层目录，语言为子目录：

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

      文档目录结构如下：

      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 获取当前版本，比如：

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

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

      按版本搜索

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

      rspress.config.ts
      import { defineConfig } from '@rspress/core';

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