侧边栏
侧边栏的作用：将多个相关文档组织成有序树结构，在这些文档页面中统一显示侧边栏导航，支持在文档间显示“上一页 / 下一页”按钮。
不要在侧边栏上浪费时间！要么使用 sidebar.js 的自动生成，尽量简单使用。要么自己编写插件，按自己的规则生成。
启用侧边栏
指定侧边栏配置文件来启用侧边栏。
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};
侧边栏配置文件以 Node. js 环境执行，不能使用浏览器 API、React 或 JSX。
sidebar.js
如果未指定 sidebarPath，Docusaurus 会使用 docs 文件夹的文件系统结构自动为你生成一个侧边栏。默认情况下 sidebar.js 的配置是这样的：
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // 从 docs 根目录生成
},
],
};
侧边栏对象
侧边栏支持各种项目类型：
| 类型 | 描述 |
|---|---|
category | 一个分类，可以包含子条目（包括子类别、文档、链接等） |
doc | 指向一个文档，使用文档的 id |
link | 外部或内部链接，带标签和 URL/href |
autogenerated | 自动生成条目，扫描一个目录下的文档与子目录 |
ref | 链接到文档页面，而不使项目参与导航生成 |
html | 在项目的位置呈现纯 HTML |
链接到文档
使用 doc 类型链接到文档页面并将该文档分配给侧边栏：
type SidebarItemDoc =
// Normal syntax
| {
type: 'doc';
id: string;
label: string; // Sidebar label text
key?: string; // Sidebar key to uniquely identify the item
className?: string; // Class name for sidebar label
customProps?: Record<string, unknown>; // Custom props
}
// Shorthand syntax
| string; // docId shortcut
示例：
export default {
mySidebar: [
// Normal syntax:
{
type: 'doc',
id: 'doc1', // document ID
label: 'Getting started', // sidebar label
},
// Shorthand syntax:
'doc2', // document ID
],
};
如果您使用文档速记或自动生成的侧边栏，您将无法通过项目定义自定义侧边栏标签。但是，您可以在该文档中使用 sidebar_label Markdown front matter，该 Front，其优先级高于侧边栏项中的标签键。同样，您可以使用 sidebar_custom_props 声明文档页面的自定义元数据。
对象的属性：
label：显示名称items：子条目数组collapsed：是否默认折叠（对于分类）link（对 category）可定义分类导航行为（如生成索引页面） ([Docusaurus][1])className：可给条目添加 CSS 类名，用于样式定制customProps：可携带自定义属性（例如徽章、特色标记等）key：给条目设一个唯一标识符，用于避免国际化 key 冲突或帮助组件识别栏目信息 ([Docusaurus][1])
复杂示例：
export default {
// 定义一个名为 mySidebar 的侧边栏
mySidebar: [
{
// 侧边栏项目类型：category（可折叠的分类/分组）
type: 'category',
// 分类的显示标签（标题）
label: 'Getting Started',
// 分类下的子项目数组
items: [
{
// 子项目类型：doc（指向一个文档文件）
type: 'doc',
// 文档的 ID，对应于 docs 目录下的文件名（不含扩展名）
id: 'doc1',
},
],
},
{
// 第二个分类
type: 'category',
// 分类的显示标签
label: 'Docusaurus',
// 分类下的子项目数组
items: [
{
// 指向 ID 为 'doc2' 的文档
type: 'doc',
id: 'doc2',
},
{
// 指向 ID 为 'doc3' 的文档
type: 'doc',
id: 'doc3',
},
],
},
{
// 侧边栏项目类型：link（外部链接）
type: 'link',
// 链接的显示标签
label: 'Learn more',
// 链接的目标 URL
href: 'https://example.com',
},
],
};
如果目录变化，需要手动更新 sidebar.js ，否则 sidebar 就失效了。
建议简单配置
随着文档数量和分类增加
// 目录结构
docs
├── computer
│ ├── intro.md
│ ├── os.md
│ ├── ...数百个.md
│ └── networking.md
└── biology
├── intro.md
├── ...数百个.md
├── genetics.md
└── ecology.md
为 docs 目录下不同文件夹配置单独的侧 边栏：
// sidebars.js
const sidebars = {
// 计算机类文档
computerSidebar: [{ type: "autogenerated", dirName: "computer" }],
// 生物类文档
biologySidebar: [{ type: "autogenerated", dirName: "biology" }],
};
module.exports = sidebars;
更好的方案
不使用 sidebar.js 。写一个自动生成 sidebar 的插件：自动将 docs/分类 生成 sidebar。例如目录 docs/linux → sidebar linux ， docs/html → html ， docs/css → css 。不论多少分类，都可以自动生成 sidebar。
主题配置：侧边栏行为控制
显示【隐藏侧边栏】按钮
通过启用该 themeConfig.docs.sidebar.hideable 选项，您可以使整个侧边栏可隐藏，让用户更好地专注于内容。当在中等大小的屏幕（例如平板电脑）上消费内容时，这尤其有用。
export default {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};
自动折叠类别
当展开一个分类时，自动折叠其他同级分类，有助于内容聚焦。
export default {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};
面包屑（Breadcrumbs）
默认情况下，每个文档顶部会根据其在侧边栏中的路径生成面包屑导航： 主页 > linux > intro
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: true,
},
},
],
],
};
传递唯一 key
传递唯一键属性可以帮助唯一标识侧边栏项。有时其他属性（如标签 ）不足以将两个侧边栏项彼此区分开来。
{
type: 'category',
label: 'API', // You may have multiple categories with this widespread label
key: 'api-for-feature-1', // and now, they can be uniquely identified
};
ref
当你想要从若干个侧边栏链接到同一篇文档时，ref 会很有用。
export default {
tutorialSidebar: {
'Category A': [
'doc1',
'doc2',
{type: 'ref', id: 'commonDoc'},
'doc5',
],
},
apiSidebar: ['doc3', 'doc4', 'commonDoc'],
};