自动化导航栏/侧边栏
在 Rspress 中,除了在配置文件中通过 themeConfig
声明 nav 和 sidebar, 你也可以通过声明 _meta.json
描述文件来自动化生成导航栏和侧边栏,我们更加推荐后者,因为可以使配置文件更加简洁和清晰。
提示
当配置文件 rspress.config.ts
中没有 nav
和 sidebar
配置的情况下,自动化导航栏/侧边栏才会生效。
基础概念
首先,_meta.json
可以分为两类:导航栏级别和侧边栏级别。两者的区别在于,导航级别的 _meta.json
位于文档根目录中,而侧边栏级别的 _meta.json
位于文档根目录的子目录中。比如:
docs
├── _meta.json // 导航栏级别
└── guides
├── _meta.json // 侧边栏级别
├── introduction.mdx
└── advanced
├── _meta.json // 侧边栏级别
└── plugin-development.md
如果你的文档使用了国际化,那么导航栏级别的 _meta.json
会放置在对应语言目录下,比如:
docs
├── en
│ ├── _meta.json // 导航栏级别
│ └── guides
│ ├── _meta.json // 侧边栏级别
│ ├── introduction.mdx
│ ├── install.mdx
│ └── advanced
│ ├── _meta.json // 侧边栏级别
│ └── plugin-development.md
└── zh
├── _meta.json // 导航栏级别
└── guides
├── _meta.json // 侧边栏级别
├── introduction.mdx
├── install.mdx
└── advanced
├── _meta.json // 侧边栏级别
└── plugin-development.md
导航栏级别配置
在导航栏级别的情况中,你可以在 _meta.json
中填入一个数组,其类型跟默认主题的 nav 配置完全一致,详情可以参考 nav 配置。比如:
[
{
"text": "Guide",
"link": "/guides/introduction",
"activeMatch": "^/guides/"
}
]
侧边栏级别配置
在侧边栏级别的情况中,你可以在 _meta.json
中填入一个数组,数组每一项的类型如下:
export type SideMetaItem =
| string
| {
type: 'file';
name: string;
label?: string;
tag?: string;
overviewHeaders?: number[];
}
| {
type: 'dir';
name: string;
label?: string;
collapsible?: boolean;
collapsed?: boolean;
tag?: string;
overviewHeaders?: number[];
}
| {
type: 'divider';
dashed?: boolean;
}
| {
type: 'section-header';
label: string;
tag?: string;
};
string
当类型为 string
时,表示该项是一个文件,文件名为该字符串,比如:
其中文件名可以带后缀,也可以不带后缀,比如 introduction
会被解析为 introduction.mdx
。
object
当类型为对象形式时,你可以描述为一个文件、目录或者自定义链接。
在描述文件的情况下,类型如下:
{
type: 'file';
name: string;
label?: string;
overviewHeaders?: number[];
}
其中,name
表示文件名,同时支持带
/不带
后缀,label
表示该文件在侧边栏中的显示名称,为可选值,如果未填则会自动取文档中的 h1 标题。overviewHeaders
表示该文件在预览页中展示的标题级别,为可选值,默认为 [2]
。比如:
{
"type": "file",
"name": "introduction",
"label": "Introduction"
}
在描述目录的情况下,类型如下:
{
type: 'dir';
name: string;
label: string;
collapsible?: boolean;
collapsed?: boolean;
overviewHeaders?: number[];
}
其中,name
表示目录名,label
表示该目录在侧边栏中的显示名称,collapsible
表示该目录是否可以折叠,collapsed
表示该目录是否默认折叠,overviewHeaders
表示该目录下的文件在预览页中展示的标题级别,为可选值,默认为 [2]
。比如:
{
"type": "dir",
"name": "advanced",
"label": "Advanced",
"collapsible": true,
"collapsed": false
}
在描述分割线的情况下,类型如下:
{
type: 'divider';
dashed?: boolean;
}
dashed
为 true
时表示该分割线是虚线,否则是实线。
提示
如果想要点击侧边栏目录显示某篇文档,你可以在当前目录同级创建一个同名的 md(x)
文件,比如:
docs
├── advanced.mdx
└── advanced
├── _meta.json
└── ...
这样,当你点击 Advanced
目录时,会显示 advanced.mdx
文件的内容。
在描述分组标题的情况下,类型如下:
{
type: 'section-header';
label: string;
}
其中,label
表示该分组标题在侧边栏中的显示名称,比如:
{
"type": "section-header",
"label": "Section Header"
}
这样,你可以在侧边栏中添加分组标题,方便对文档和目录进行分组。一般情况下,你可以配合 divider
使用,来更好的区分不同的分组。比如:
[
{
"type": "section-header",
"label": "Section 1"
},
"introduction",
{
"type": "divider"
},
{
"type": "section-header",
"label": "Section 2"
},
"advanced"
]
在描述自定义链接的情况下,类型如下:
{
type: 'custom-link';
label: string;
link: string;
}
其中,label
表示该链接在侧边栏中的显示名称,link
表示该链接的跳转地址,比如:
{
"type": "custom-link",
"label": "My Link",
"link": "/my-link"
}
link
支持外部链接,比如:
{
"type": "custom-link",
"link": "https://github.com",
"label": "GitHub"
}
完整示例
下面是一个完整的示例,用到了上述的三种类型:
[
"install",
{
"type": "file",
"name": "introduction",
"label": "Introduction"
},
{
"type": "dir",
"name": "advanced",
"label": "Advanced",
"collapsible": true,
"collapsed": false
},
{
"type": "custom-link",
"label": "My Link",
"link": "/my-link"
}
]
无配置用法
某些目录下你可以不配置 _meta.json
,让框架自动帮你生成侧边栏。这需要保证目录下仅包含文档,而不包含子目录,并且你对文档的顺序没有要求。比如现在有如下的文档结构:
docs
├── _meta.json
└── guides
├── _meta.json
└── basic
├── introduction.mdx
├── install.mdx
└── plugin-development.md
在 guides
目录中你可以配置 _meta.json
内容如下:
[
{
"type": "dir",
"name": "basic",
"label": "Basic",
"collapsible": true,
"collapsed": false
}
]
而在 basic
目录中,你可以不配置 _meta.json
,框架会自动帮你生成侧边栏,默认按照文件名的字母顺序排序。如果你想要自定义顺序,可以在文件名前加上数字前缀,比如:
basic
├── 1-introduction.mdx
├── 2-install.mdx
└── 3-plugin-development.md
标题前添加 svg 图标
此外,你还可以通过 tag
配置在标题前添加图标,比如:
_meta.json
{
"type": "file",
"name": "introduction",
"label": "Introduction",
"tag": "<svg width=\"1em\" height=\"1em\" viewBox=\"0 0 32 32\"><path fill=\"currentColor\" d=\"M4 6h24v2H4zm0 18h24v2H4zm0-12h24v2H4zm0 6h24v2H4z\"/></svg>"
}
tag
的值为 svg 标签字符串或者图片 URL,你可以将其配置到导航栏或者侧边栏中。