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

侧边栏

创建侧边栏可以:

  • 分组多篇相关文档
  • 在每篇文档旁显示侧边栏
  • Provide paginated navigation, with next/previous button

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

  1. Define a file that exports a dictionary of sidebar objects.
  2. 直接将这个对象传入 @docusaurus/plugin-docs,或者通过 @docusaurus/preset-classic 传入。
docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
},
],
],
};

This section serves as an overview of miscellaneous features of the doc sidebar. In the following sections, we will more systematically introduce the following concepts:

默认侧边栏

If the sidebarPath is unspecified, Docusaurus automatically generates a sidebar for you, by using the filesystem structure of the docs folder:

sidebars.js
module.exports = {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
},
],
};

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

A sidebar at its crux is a hierarchy of categories, doc links, and other hyperlinks.

type Sidebar =
// Normal syntax
| SidebarItem[]
// Shorthand syntax
| {[categoryLabel: string]: SidebarItem[]};

举个例子:

sidebars.js
module.exports = {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};

This is a sidebars file that exports one sidebar, called mySidebar. It has three top-level items: two categories and one external link. Within each category, there are a few doc links.

A sidebars file can contain multiple sidebar objects, identified by their object keys.

type SidebarsFile = {
[sidebarID: string]: Sidebar;
};

主题配置

Hideable sidebar

By enabling the themeConfig.hideableSidebar option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).

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

Auto-collapse sidebar categories

The themeConfig.autoCollapseSidebarCategories option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.

docusaurus.config.js
module.exports = {
themeConfig: {
autoCollapseSidebarCategories: 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: {
/* props */
},
};

复杂侧边栏示例

A real-world example from the Docusaurus site:

sidebars.js
const sidebars = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
link: {
type: 'generated-index',
},
collapsed: false,
items: [
'installation',
'configuration',
'playground',
'typescript-support',
],
},
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Docusaurus Guides',
description:
"Let's learn about the most important Docusaurus concepts!",
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: [
'guides/creating-pages',
{
type: 'category',
label: 'Docs',
link: {
type: 'doc',
id: 'guides/docs/introduction',
},
items: [
'guides/docs/create-doc',
{
type: 'category',
label: 'Sidebar',
link: {
type: 'doc',
id: 'guides/docs/sidebar/index',
},
items: [
'guides/docs/sidebar/items',
'guides/docs/sidebar/autogenerated',
'guides/docs/sidebar/multiple-sidebars',
],
},
'guides/docs/versioning',
'guides/docs/markdown-features',
'guides/docs/multi-instance',
],
},
'blog',
{
type: 'category',
label: 'Markdown Features',
link: {
type: 'doc',
id: 'guides/markdown-features/introduction',
},
items: [
'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',
'using-plugins',
'deployment',
{
type: 'category',
label: 'Internationalization',
link: {type: 'doc', id: 'i18n/introduction'},
items: [
{
type: 'doc',
id: 'i18n/tutorial',
label: 'Tutorial',
},
{
type: 'doc',
id: 'i18n/git',
label: 'Using Git',
},
{
type: 'doc',
id: 'i18n/crowdin',
label: 'Using Crowdin',
},
],
},
'guides/whats-next',
],
},
{
type: 'category',
label: 'Advanced Guides',
link: {type: 'doc', id: 'advanced/index'},
items: [
'advanced/architecture',
'advanced/plugins',
'advanced/routing',
'advanced/swizzling',
'advanced/ssg',
],
},
{
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;