跳转至主内容
Version: 2.0.0-beta.9

侧边栏

创建侧边栏可以:

  • 分组多篇相关文档
  • 在每篇文档旁显示侧边栏
  • 提供分页导航,附带下一个/上一个按钮

要在您的 Docusaurus 站点上使用侧边栏:

  1. 定义一个导出侧边栏对象的文件。
  2. 直接将这个对象传入 @docusaurus/plugin-docs,或者通过 @docusaurus/preset-classic 传入。
docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
},
],
],
};

默认侧边栏

默认情况下,Docusaurus 会通过文件系统中的 docs 文件夹结构来自动为您生成侧边栏

sidebars.js
module.exports = {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // 从 docs 文件夹生成侧边栏切片 (或 versioned_docs/<版本>)
},
],
};

您也可显性定义您的侧边栏。

侧边栏由侧边栏项构成。

type Sidebar =
// 正常语法
| SidebarItem[]

// 简写语法
| Record<
string, // 分类标签
SidebarItem[] // 分类项
>;

侧边栏文件可包含多个侧边栏对象

type SidebarsFile = Record<
string, // 侧边栏 id
Sidebar
>;

示例:

sidebars.js
module.exports = {
mySidebar: [
{
type: 'category',
label: '快速入门',
items: ['doc1'],
},
{
type: 'category',
label: 'Docusaurus',
items: ['doc2', 'doc3'],
},
],
};

请注意以下几点:

  • 这是一个侧边栏 mySidebar,包含 5 个侧边栏项
  • 快速入门Docusaurus 是侧边栏分类
  • doc1doc2doc3 是侧边栏文档
tip

您可使用简写语法来更简洁地表达。

sidebars.js
module.exports = {
mySidebar: {
'快速入门': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
};

使用多个侧边栏

你可以为每组想要分类到一起的 Markdown 文件创建一个侧边栏。

tip

Docusaurus 就是使用多侧边栏的典范之一:

示例:

sidebars.js
module.exports = {
tutorialSidebar: {
'分类 A': ['doc1', 'doc2'],
},
apiSidebar: ['doc3', 'doc4'],
};
note

tutorialSidebarapiSidebar 为侧边栏的代码编号,可随意修改。

在浏览:

  • doc1doc2 时将显示 tutorialSidebar
  • doc3doc4 时将显示 apiSidebar

分页导航将在同一侧边栏内链接的文档内显示下一篇和上一篇按钮

理解侧边栏项

SidebarItem 是定义在侧边栏树中的项。

侧边栏项有多种类型:

  • Doc:文档页面的链接,分配到侧边栏
  • Ref:文档页面的链接,不分配到侧边栏
  • Link:内部或外部页面链接
  • Category:创建侧边栏项分类层级
  • Autogenerated:自动生成侧边栏切片(Slice)

使用 doc 类型链接至文档页面,并分配链接文档至侧边栏:

type SidebarItemDoc =
// Normal syntax
| {
type: 'doc';
id: string;
label: string; // Sidebar label text
className?: string; // Class name for sidebar label
}

// Shorthand syntax
| string; // docId shortcut

示例:

sidebars.js
module.exports = {
mySidebar: [
// 正常语法:
{
type: 'doc',
id: 'doc1', // 文档 ID
label: 'Getting started', // 侧边栏标签
},

// 简写语法:
'doc2', // 文档 ID
],
};

Markdown 前言 sidebar_labelSidebarItemDoc 中的 label 键有更高的优先度。

note

不要将同一文档分配至多个侧边栏中:若有需要,请使用ref

使用 ref 类型链接至文档页面,但不分配链接文档至侧边栏:

type SidebarItemRef = {
type: 'ref';
id: string;
};

示例:

sidebars.js
module.exports = {
mySidebar: [
{
type: 'ref',
id: 'doc1', // 文档 id(string)。
},
],
};

浏览 doc1 时,Docusaurus 将不会显示 mySidebar 侧边栏。

使用 link 类型链接到任何非文档的页面(内部或外部链接) 。

type SidebarItemLink = {
type: 'link';
label: string;
href: string;
className?: string;
};

示例:

sidebars.js
module.exports = {
myLinksSidebar: [
// 外部链接
{
type: 'link',
label: 'Facebook', // 链接标签
href: 'https://facebook.com', // 外部 URL
},

// 内部链接
{
type: 'link',
label: 'Home', // 链接标签
href: '/', // 内部路径
},
],
};

使用 category 类型创建侧边栏项的层次结构。

type SidebarItemCategory = {
type: 'category';
label: string; // Sidebar label text.
items: SidebarItem[]; // Array of sidebar items.
className?: string;

// Category options:
collapsible: boolean; // Set the category to be collapsible
collapsed: boolean; // Set the category to be initially collapsed or open by default
};

示例:

sidebars.js
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

当您不需要分类选项时,您使用 简写语法

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};

Collapsible categories

我们支持设置展开/折叠分类。 下拉菜单默认是可折叠的,但你可以通过 collapsible: false 禁用折叠功能。

sidebars.js
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
items: [
'creating-pages',
{
type: 'category',
collapsible: false,
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};

要使得所有菜单都默认不可折叠,可以在 plugin-docs 中设置 sidebarCollapsible: false

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsible: false,
},
},
],
],
};
note

sidebars.js 中的配置优先于插件配置,所以当 sidebarCollapsible 被全局设置为 false 时,仍可以让某些菜单变得可折叠。

Expanded categories by default

可折叠菜单默认被折叠。 如果你希望它们在首次渲染时就是展开状态,你可以将 collapsed 设置为 false

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};

collapsible 类似,你也可以在全局配置中将 options.sidebarCollapsed 设置为 falsesidebars.js 中的 collapsed 选项仍会覆盖这一设置。

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsed: false,
},
},
],
],
};
caution

当一个菜单同时被设置了 collapsed: truecollapsible: false(要么通过 sidebars.js 要么通过插件全局设置),后者将被优先处理,而菜单仍然被渲染为展开状态。

Docusaurus 可以从您的文件系统结构自动创建侧边栏

Docusaurus 将自动转换 autogenerated 项至侧边栏切片:即一系列类型为 doccategory 的项。

type SidebarItemAutogenerated = {
type: 'autogenerated';
dirName: string; // 生成侧边栏切片的源文件夹(相对文档目录)
};

Docusaurus 可以从您的文档文件夹中自动生成侧边栏:

sidebars.js
module.exports = {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' 即当前的文档文件夹
},
],
};

您也可以在侧边栏中使用多个 autogenerated,并与普通的侧边栏项混合:

sidebars.js
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'],
},
],
};

自动生成侧边栏元数据

默认情况下,侧边栏切片将按字母顺序(使用文件和文件夹名称)生成。

若生成的侧边栏不合您意,您可为文档和分类分配附加元数据。

对于文档而言,请添加额外的前言部分:

docs/tutorials/tutorial-easy.md
---
sidebar_label: Easy
sidebar_position: 2
---

# Easy Tutorial

This is the easy tutorial!

对于类别而言,请在合适的文件夹中添加 _category_.json_category_.yml 文件:

docs/tutorials/_category_.json
{
"label": "Tutorial",
"position": 3,
"className": "red"
}
docs/tutorials/_category_.yml
label: 'Tutorial'
position: 2.5 # float position is supported
collapsible: true # make the category collapsible
collapsed: 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 链接

docs/02-Tutorial Easy/01-First Part.md
- 看看[教程结语](../04-End.md);
+ 看看[教程结语](../05-End.md);

自定义侧边栏项生成器

您可在文档插件(或预设)中提供自定义的 sidebarItemsGenerator 函数:

docusaurus.config.js
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

复用并改进默认生成器,不要造轮子。

请根据您的用例添加、更新、筛选、重新排序侧边栏项:

docusaurus.config.js
// 反转侧边栏排序(包括嵌套分类项)
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);
},
},
],
],
};

Hideable sidebar

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).

docusaurus.config.js
module.exports = {
themeConfig: {
hideableSidebar: true,
},
};

Passing custom props

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 网站的真实示例:

sidebars.js
// @ts-check
const sidebars = {
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-metadata',
],
},
'styling-layout',
'static-assets',
'search',
'browser-support',
'seo',
'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',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
module.exports = sidebars;