侧边栏
创建侧边栏可以：
- 分组多篇相关文档
- 在每篇文档旁显示侧边栏
- 提供分页导航，附带下一个/上一个按钮
要在您的 Docusaurus 站点上使用侧边栏：
- 定义导出侧边栏对象的文件。
- 直接将此对象传入
@docusaurus/plugin-docs或通过@docusaurus/preset-classic传入。
module.exports = { presets: [ [ '@docusaurus/preset-classic', { docs: { sidebarPath: require.resolve('./sidebars.js'), }, }, ], ],};默认侧边栏#
默认情况下，Docusaurus 会通过文件系统中的 docs 文件夹结构来自动为您生成侧边栏：
module.exports = { mySidebar: [ { type: 'autogenerated', dirName: '.', // 从 docs 文件夹生成侧边栏切片 (或 versioned_docs/<版本>) }, ],};您也可显性定义您的侧边栏。
侧边栏对象#
侧边栏由侧边栏项树构成。
type Sidebar = // 正常语法 | SidebarItem[]
// 简写语法 | Record< string, // 分类标签 SidebarItem[] // 分类项 >;侧边栏文件可包含多个侧边栏对象。
type SidebarsFile = Record< string, // 侧边栏 id Sidebar>;示例：
module.exports = { mySidebar: [ { type: 'category', label: '快速入门', items: ['doc1'], }, { type: 'category', label: 'Docusaurus', items: ['doc2', 'doc3'], }, ],};请注意以下几点：
- 这是一个侧边栏
mySidebar，包含 5 个侧边栏项 快速入门及Docusaurus是侧边栏分类doc1、doc2和doc3是侧边栏文档
tip
您可使用简写语法来更简洁地表达。
module.exports = { mySidebar: { '快速入门': ['doc1'], Docusaurus: ['doc2', 'doc3'], },};使用多个侧边栏#
You can create a sidebar for each set of Markdown files that you want to group together.
示例：
module.exports = { tutorialSidebar: { '分类 A': ['doc1', 'doc2'], }, apiSidebar: ['doc3', 'doc4'],};note
键 tutorialSidebar 和 apiSidebar 为侧边栏的代码编号，可随意修改。
在浏览：
doc1或doc2时将显示tutorialSidebardoc3或doc4时将显示apiSidebar
分页导航将在同一侧边栏内链接的文档内显示下一篇和上一篇按钮。
理解侧边栏项#
SidebarItem 是定义在侧边栏树中的项。
侧边栏项有多种类型：
- Doc：文档页面的链接，分配到侧边栏
- Ref：文档页面的链接，不分配到侧边栏
- Link：内部或外部页面链接
- Category：创建侧边栏项分类层级
- Autogenerated：自动生成侧边栏切片（Slice）
Doc - 文档链接#
使用 doc 类型链接至文档页面，并分配链接文档至侧边栏：
type SidebarItemDoc = // 正常语法 | { type: 'doc'; id: string; label: string; // 侧边栏标签文本 }
// 简写语法 | string; // docId 快捷方式示例：
module.exports = { mySidebar: [ // 正常语法： { type: 'doc', id: 'doc1', // 文档 ID label: 'Getting started', // 侧边栏标签 },
// 简写语法： 'doc2', // 文档 ID ],};Markdown 前言 sidebar_label 比 SidebarItemDoc 中的 label 键有更高的优先度。
note
不要将同一文档分配至多个侧边栏中：若有需要，请使用ref。
Ref - 文档链接，无侧边栏#
使用 ref 类型链接至文档页面，但不分配链接文档至侧边栏：
type SidebarItemRef = { type: 'ref'; id: string;};示例：
module.exports = { mySidebar: [ { type: 'ref', id: 'doc1', // 文档 id（string）。 }, ],};浏览 doc1 时，Docusaurus 将不会显示 mySidebar 侧边栏。
Link - 任意页面链接#
使用 link 类型链接到任何非文档的页面（内部或外部链接） 。
type SidebarItemLink = { type: 'link'; label: string; href: string;};示例：
module.exports = { myLinksSidebar: [ // 外部链接 { type: 'link', label: 'Facebook', // 链接标签 href: 'https://facebook.com', // 外部 URL },
// 内部链接 { type: 'link', label: 'Home', // 链接标签 href: '/', // 内部路径 }, ],};Category - 创建分类层级#
使用 category 类型创建侧边栏项的层次结构。
type SidebarItemCategory = { type: 'category'; label: string; // 侧边栏标签文本 items: SidebarItem[]; // 侧边栏项数组
// Category options: collapsible: boolean; // Set the category to be collapsible collapsed: boolean; // Set the category to be initially collapsed or open by default};示例：
module.exports = { docs: [ { type: 'category', label: 'Guides', collapsible: true, collapsed: false, items: [ 'creating-pages', { type: 'category', label: 'Docs', items: ['introduction', 'sidebar', 'markdown-features', 'versioning'], }, ], }, ],};tip
当您不需要分类选项时，您使用 简写语法：
module.exports = { docs: { Guides: [ 'creating-pages', { Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'], }, ], },};折叠分类#
We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with collapsible: false.
module.exports = { docs: [ { type: 'category', label: 'Guides', items: [ 'creating-pages', { type: 'category', collapsible: false, label: 'Docs', items: ['introduction', 'sidebar', 'markdown-features', 'versioning'], }, ], }, ],};To make all categories non-collapsible by default, set the sidebarCollapsible option in plugin-docs to false:
module.exports = { presets: [ [ '@docusaurus/preset-classic', { docs: { sidebarCollapsible: false, }, }, ], ],};note
The option in sidebars.js takes precedence over plugin configuration, so it is possible to make certain categories collapsible when sidebarCollapsible is set to false globally.
默认展开分类#
Collapsible categories are collapsed by default. If you want them to be expanded on first render, you can set collapsed to false:
module.exports = { docs: { Guides: [ 'creating-pages', { type: 'category', label: 'Docs', collapsed: false, items: ['markdown-features', 'sidebar', 'versioning'], }, ], },};Similar to collapsible, you can also set the global configuration options.sidebarCollapsed to false. Individual collapsed options in sidebars.js will still take precedence over this configuration.
module.exports = { presets: [ [ '@docusaurus/preset-classic', { docs: { sidebarCollapsed: false, }, }, ], ],};caution
When a category has collapsed: true but collapsible: false (either through sidebars.js or through plugin configuration), the latter takes precedence and the category is still rendered as expanded.
Autogenerated - 生成侧边栏#
Docusaurus 可以从您的文件系统结构中自动创建侧边栏。
Docusaurus 将自动转换 autogenerated 项至侧边栏切片：即一系列类型为 doc 和 category 的项。
type SidebarItemAutogenerated = { type: 'autogenerated'; dirName: string; // 生成侧边栏切片的源文件夹（相对文档目录）};Docusaurus 可以从您的文档文件夹中自动生成侧边栏：
module.exports = { myAutogeneratedSidebar: [ { type: 'autogenerated', dirName: '.', // '.' 即当前的文档文件夹 }, ],};您也可以在侧边栏中使用多个 autogenerated 项，并与普通的侧边栏项混合：
module.exports = { mySidebar: [ 'intro', { type: 'category', label: '教程', items: [ 'tutorial-intro', { type: 'autogenerated', dirName: 'tutorials/easy', // 从 docs/tutorials/easy 文件夹自动生成侧边栏切片 }, 'tutorial-medium', { type: 'autogenerated', dirName: 'tutorials/advanced', // docs/tutorials/hard 文件夹自动生成侧边栏切片 }, 'tutorial-end', ], }, { type: 'autogenerated', dirName: 'guides', // docs/guides 文件夹自动生成侧边栏切片 }, { type: 'category', label: '社群', items: ['team', 'chat'], }, ],};自动生成侧边栏元数据#
默认情况下，侧边栏切片将按字母顺序（使用文件和文件夹名称）生成。
若生成的侧边栏不合您意，您可为文档和分类分配附加元数据。
对于文档而言，请添加额外的前言部分：
---sidebar_label: Easysidebar_position: 2---
# Easy Tutorial
This is the easy tutorial!对于类别而言，请在合适的文件夹中添加 _category_.json 或 _category_.yml 文件：
{ "label": "教程", "position": 3}label: 'Tutorial'position: 2.5 # float position is supportedcollapsible: true # make the category collapsiblecollapsed: false # keep the category open by default信息
位置元数据仅用在侧边栏切片内：Docusaurus 不会重新排序您侧边栏的其他项。
使用数字前缀#
排序自动生成的侧边栏之简单方法其一是为文档及文件夹添加数字前缀：
docs├── 01-简介.md├── 02-简单教程│ ├── 01-第一部分.md│ ├── 02-第二部分.md│ └── 03-结语.md├── 03-困难教程│ ├── 01-第一部分.md│ ├── 02-第二部分.md│ ├── 03-第三部分.md│ └── 04-结语.md└── 04-结语.md为了更方便使用此功能，Docusaurus 支持多数字前缀模式。
By default, Docusaurus will remove the number prefix from the doc id, title, label and URL paths.
caution
我们推荐您使用附加元数据。
更新数字前缀很麻烦，因为可能需要更新多个已有的 Markdown 链接：
- 看看[教程结语](../04-End.md);+ 看看[教程结语](../05-End.md);自定义侧边栏项生成器#
您可在文档插件（或预设）中提供自定义的 sidebarItemsGenerator 函数：
module.exports = { plugins: [ [ '@docusaurus/plugin-content-docs', { sidebarItemsGenerator: async function ({ defaultSidebarItemsGenerator, numberPrefixParser, item, version, docs, }) { // 示例：返回硬编码的静态侧边栏项 return [ {type: 'doc', id: 'doc1'}, {type: 'doc', id: 'doc2'}, ]; }, }, ], ],};tip
请复用并改进默认生成器，不要造轮子。
请根据您的用例添加、更新、筛选、重新排序侧边栏项：
// 反转侧边栏排序（包括嵌套分类项）function reverseSidebarItems(items) { // 反转分类内的项 const result = items.map((item) => { if (item.type === 'category') { return {...item, items: reverseSidebarItems(item.items)}; } return item; }); // 反转当前层级的项 result.reverse(); return result;}
module.exports = { plugins: [ [ '@docusaurus/plugin-content-docs', { sidebarItemsGenerator: async function ({ defaultSidebarItemsGenerator, ...args }) { const sidebarItems = await defaultSidebarItemsGenerator(args); return reverseSidebarItems(sidebarItems); }, }, ], ],};隐藏侧边栏#
Using the enabled themeConfig.hideableSidebar option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).
module.exports = { themeConfig: { hideableSidebar: true, },};传递自定义属性#
To pass in custom props to a swizzled sidebar item, add the optional customProps object to any of the items:
{ type: 'doc', id: 'doc1', customProps: { /* 属性 */ }}复杂侧边栏示例#
来自 Docusaurus 网站的真实示例：
module.exports = { docs: [ 'introduction', { type: 'category', label: 'Getting Started', collapsed: false, items: [ 'installation', 'configuration', 'playground', 'typescript-support', ], }, { type: 'category', label: 'Guides', items: [ 'guides/creating-pages', { Docs: [ 'guides/docs/introduction', 'guides/docs/create-doc', 'guides/docs/sidebar', 'guides/docs/versioning', 'guides/docs/markdown-features', 'guides/docs/multi-instance', ], }, 'blog', { type: 'category', label: 'Markdown Features', items: [ 'guides/markdown-features/introduction', 'guides/markdown-features/react', 'guides/markdown-features/tabs', 'guides/markdown-features/code-blocks', 'guides/markdown-features/admonitions', 'guides/markdown-features/headings', 'guides/markdown-features/inline-toc', 'guides/markdown-features/assets', 'guides/markdown-features/plugins', 'guides/markdown-features/math-equations', 'guides/markdown-features/head-metadatas', ], }, 'styling-layout', 'static-assets', 'search', 'browser-support', 'deployment', { type: 'category', label: 'Internationalization', items: [ { type: 'doc', id: 'i18n/introduction', label: 'Introduction', }, { type: 'doc', id: 'i18n/tutorial', label: 'Tutorial', }, { type: 'doc', id: 'i18n/git', label: 'Using Git', }, { type: 'doc', id: 'i18n/crowdin', label: 'Using Crowdin', }, ], }, ], }, { type: 'category', label: 'Advanced Guides', items: ['using-plugins', 'using-themes', 'presets'], }, { type: 'category', label: 'Migrating from v1 to v2', items: [ 'migration/migration-overview', 'migration/migration-automated', 'migration/migration-manual', 'migration/migration-versioned-sites', 'migration/migration-translated-sites', ], }, ], api: [ 'cli', 'docusaurus-core', 'api/docusaurus.config.js', 'lifecycle-apis', { type: 'category', label: 'Plugins', items: [ 'api/plugins/plugins-overview', 'api/plugins/plugin-content-docs', 'api/plugins/plugin-content-blog', 'api/plugins/plugin-content-pages', 'api/plugins/plugin-client-redirects', 'api/plugins/plugin-debug', 'api/plugins/plugin-google-analytics', 'api/plugins/plugin-google-gtag', 'api/plugins/plugin-ideal-image', 'api/plugins/plugin-pwa', 'api/plugins/plugin-sitemap', ], }, { type: 'category', label: 'Themes', items: [ 'api/themes/themes-overview', 'api/themes/theme-configuration', 'api/themes/theme-classic', 'api/themes/theme-bootstrap', 'api/themes/theme-live-codeblock', 'api/themes/theme-search-algolia', ], }, ],};