自动化导航栏/侧边栏

在 Rspress 中，除了在配置文件中通过 themeConfig 声明 nav 和 sidebar， 你也可以通过声明 _meta.json 描述文件来自动化生成导航栏和侧边栏，我们更加推荐后者，因为可以使配置文件更加简洁和清晰。

提示

当配置文件 rspress.config.ts 中没有 nav 和 sidebar 配置的情况下，自动化导航栏/侧边栏才会生效。

基础概念

首先，_meta.json 可以分为两类：导航栏级别和侧边栏级别。两者的区别在于，导航级别的 _meta.json 位于文档根目录中，而侧边栏级别的 _meta.json 位于文档根目录的子目录中。比如:

  1. docs
  2. ├── _meta.json // 导航栏级别
  3. └── guides
  4.     ├── _meta.json // 侧边栏级别
  5.     ├── introduction.mdx
  6.     └── advanced
  7.         ├── _meta.json // 侧边栏级别
  8.         └── plugin-development.md

如果你的文档使用了国际化，那么导航栏级别的 _meta.json 会放置在对应语言目录下，比如：

  1. docs
  2. ├── en
  3. │   ├── _meta.json // 导航栏级别
  4. │   └── guides
  5. │       ├── _meta.json // 侧边栏级别
  6. │       ├── introduction.mdx
  7. │       ├── install.mdx
  8. │       └── advanced
  9. │           ├── _meta.json // 侧边栏级别
  10. │           └── plugin-development.md
  11. └── zh
  12.     ├── _meta.json // 导航栏级别
  13.     └── guides
  14.         ├── _meta.json // 侧边栏级别
  15.         ├── introduction.mdx
  16.         ├── install.mdx
  17.         └── advanced
  18.             ├── _meta.json // 侧边栏级别
  19.             └── plugin-development.md

导航栏级别配置

在导航栏级别的情况中，你可以在 _meta.json 中填入一个数组，其类型跟默认主题的 nav 配置完全一致，详情可以参考 nav 配置。比如:

  1. [
  2.   {
  3.     "text": "Guide",
  4.     "link": "/guides/introduction",
  5.     "activeMatch": "^/guides/"
  6.   }
  7. ]

侧边栏级别配置

在侧边栏级别的情况中，你可以在 _meta.json 中填入一个数组，数组每一项的类型如下:

  1. export type SideMetaItem =
  2.   | string
  3.   | {
  4.       type: 'file';
  5.       name: string;
  6.       label?: string;
  7.       tag?: string;
  8.       overviewHeaders?: number[];
  9.       context?: string;
  10.     }
  11.   | {
  12.       type: 'dir';
  13.       name: string;
  14.       label?: string;
  15.       collapsible?: boolean;
  16.       collapsed?: boolean;
  17.       tag?: string;
  18.       overviewHeaders?: number[];
  19.       context?: string;
  20.     }
  21.   | {
  22.       type: 'divider';
  23.       dashed?: boolean;
  24.     }
  25.   | {
  26.       type: 'section-header';
  27.       label: string;
  28.       tag?: string;
  29.     }
  30.   | {
  31.       type: 'custom-link';
  32.       label: string;
  33.       link: string;
  34.       context?: string;
  35.     };

string

当类型为 string 时，表示该项是一个文件，文件名为该字符串，比如:

  1. ["introduction"]

其中文件名可以带后缀，也可以不带后缀，比如 introduction 会被解析为 introduction.mdx。

object

当类型为对象形式时，你可以描述为一个文件、目录或者自定义链接。

在描述文件的情况下，类型如下:

  1. {
  2.   type: 'file';
  3.   name: string;
  4.   label?: string;
  5.   overviewHeaders?: number[];
  6.   context?: string;
  7. }

其中，name 表示文件名，同时支持带/不带后缀，label 表示该文件在侧边栏中的显示名称，为可选值，如果未填则会自动取文档中的 h1 标题。overviewHeaders 表示该文件在预览页中展示的标题级别，为可选值，默认为 [2]。context 表示在生成侧边栏时在所在的 DOM 节点添加 data-context 属性的值。为可选值，默认不会添加。比如:

  1. {
  2.   "type": "file",
  3.   "name": "introduction",
  4.   "label": "Introduction"
  5. }

在描述目录的情况下，类型如下:

  1. {
  2.   type: 'dir';
  3.   name: string;
  4.   label: string;
  5.   collapsible?: boolean;
  6.   collapsed?: boolean;
  7.   overviewHeaders?: number[];
  8.   context?: string;
  9. }

其中，name 表示目录名，label 表示该目录在侧边栏中的显示名称，collapsible 表示该目录是否可以折叠，collapsed 表示该目录是否默认折叠，overviewHeaders 表示该目录下的文件在预览页中展示的标题级别，为可选值，默认为 [2]。context 表示在生成侧边栏时在所在的 DOM 节点添加 data-context 属性的值。为可选值，默认不会添加。比如:

  1. {
  2.   "type": "dir",
  3.   "name": "advanced",
  4.   "label": "Advanced",
  5.   "collapsible": true,
  6.   "collapsed": false
  7. }

在描述分割线的情况下，类型如下：

  1. {
  2.   type: 'divider';
  3.   dashed?: boolean;
  4. }

dashed 为 true 时表示该分割线是虚线，否则是实线。

提示

如果想要点击侧边栏目录显示某篇文档，你可以在当前目录同级创建一个同名的 md(x) 文件，比如：

  1. docs
  2. ├── advanced.mdx
  3. └── advanced
  4.   ├── _meta.json
  5.   └── ...

这样，当你点击 Advanced 目录时，会显示 advanced.mdx 文件的内容。

在描述分组标题的情况下，类型如下:

  1. {
  2.   type: 'section-header';
  3.   label: string;
  4. }

其中，label 表示该分组标题在侧边栏中的显示名称，比如:

  1. {
  2.   "type": "section-header",
  3.   "label": "Section Header"
  4. }

这样，你可以在侧边栏中添加分组标题，方便对文档和目录进行分组。一般情况下，你可以配合 divider 使用，来更好的区分不同的分组。比如:

  1. [
  2.   {
  3.     "type": "section-header",
  4.     "label": "Section 1"
  5.   },
  6.   "introduction",
  7.   {
  8.     "type": "divider"
  9.   },
  10.   {
  11.     "type": "section-header",
  12.     "label": "Section 2"
  13.   },
  14.   "advanced"
  15. ]

在描述自定义链接的情况下，类型如下:

  1. {
  2.   type: 'custom-link';
  3.   label: string;
  4.   link: string;
  5.   context?: string;
  6. }

其中，label 表示该链接在侧边栏中的显示名称，link 表示该链接的跳转地址，比如:

  1. {
  2.   "type": "custom-link",
  3.   "label": "My Link",
  4.   "link": "/my-link"
  5. }

link 支持外部链接，比如:

  1. {
  2.   "type": "custom-link",
  3.   "link": "https://github.com",
  4.   "label": "GitHub"
  5. }

完整示例

下面是一个完整的示例，用到了上述的三种类型:

  1. [
  2.   "install",
  3.   {
  4.     "type": "file",
  5.     "name": "introduction",
  6.     "label": "Introduction"
  7.   },
  8.   {
  9.     "type": "dir",
  10.     "name": "advanced",
  11.     "label": "Advanced",
  12.     "collapsible": true,
  13.     "collapsed": false
  14.   },
  15.   {
  16.     "type": "custom-link",
  17.     "label": "My Link",
  18.     "link": "/my-link"
  19.   }
  20. ]

无配置用法

某些目录下你可以不配置 _meta.json，让框架自动帮你生成侧边栏。这需要保证目录下仅包含文档，而不包含子目录，并且你对文档的顺序没有要求。比如现在有如下的文档结构:

  1. docs
  2. ├── _meta.json
  3. └── guides
  4.   ├── _meta.json
  5.   └── basic
  6.     ├── introduction.mdx
  7.     ├── install.mdx
  8.     └── plugin-development.md

在 guides 目录中你可以配置 _meta.json 内容如下:

  1. [
  2.   {
  3.     "type": "dir",
  4.     "name": "basic",
  5.     "label": "Basic",
  6.     "collapsible": true,
  7.     "collapsed": false
  8.   }
  9. ]

而在 basic 目录中，你可以不配置 _meta.json，框架会自动帮你生成侧边栏，默认按照文件名的字母顺序排序。如果你想要自定义顺序，可以在文件名前加上数字前缀，比如:

  1. basic
  2.   ├── 1-introduction.mdx
  3.   ├── 2-install.mdx
  4.   └── 3-plugin-development.md

标题前添加 svg 图标

此外，你还可以通过 tag 配置在标题前添加图标，比如:

_meta.json

  1. {
  2.   "type": "file",
  3.   "name": "introduction",
  4.   "label": "Introduction",
  5.   "tag": "<svg width=\"1em\" height=\"1em\" viewBox=\"0 0 32 32\"><path fill=\"currentColor\" d=\"M4 6h24v2H4zm0 18h24v2H4zm0-12h24v2H4zm0 6h24v2H4z\"/></svg>"
  6. }

tag 的值为 svg 标签字符串或者图片 URL，你可以将其配置到导航栏或者侧边栏中。