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

侧边栏

创建侧边栏可以:

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

要在您的 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'],  },};

使用多个侧边栏#

You can create a sidebar for each set of Markdown files that you want to group together.

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 - 文档链接#

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

type SidebarItemDoc =  // 正常语法  | {      type: 'doc';      id: string;      label: string; // 侧边栏标签文本    }
  // 简写语法  | string; // docId 快捷方式

示例:

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

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

note

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

Ref - 文档链接,无侧边栏#

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

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

示例:

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

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

Link - 任意页面链接#

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

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

示例:

sidebars.js
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[]; // 侧边栏项数组
  // 分类选项:  collapsed: boolean; // 是否默认收起或展开分类};

示例:

sidebars.js
module.exports = {  docs: [    {      type: 'category',      label: '指南',      collapsed: false,      items: [        'creating-pages',        {          type: 'category',          label: '文档',          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],        },      ],    },  ],};
tip

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

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

折叠分类#

对于内容众多的网站,我们支持展开/收起分类来开关是否显示其内容。 默认情况下,分类被自动收起。 若您想设置为总是展开,您可将 themeConfig.sidebarCollapsible 设置为 false

docusaurus.config.js
module.exports = {  themeConfig: {    sidebarCollapsible: false,  },};

默认展开分类#

对于有着可折叠的分类而言,您可能希望更细微地控制特定分类。 若您想总是展开特定分类,您可将 collapsed 设置为 false

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

Autogenerated - 生成侧边栏#

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: Easysidebar_position: 2---
# Easy Tutorial
This is the easy tutorial!

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

docs/tutorials/_category_.json
{  "label": "教程",  "position": 3}
docs/tutorials/_category_.yml
label: '教程'position: 2.5 # 支持浮动位置collapsed: false # 默认展开分类
info

位置元数据仅用在侧边栏切片内: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.

注意

我们推荐您使用附加元数据

更新数字前缀很麻烦,因为可能需要更新多个已有的 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);        },      },    ],  ],};

隐藏侧边栏#

通过启用 themeConfig.hideableSidebar 选项,您可以隐藏整个侧边栏,让您的用户能专注于内容。 这更方便中等屏幕(如平板)大小的用户阅读内容。

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

传递自定义属性#

要将自定义属性传递至变换(Swizzled)后的侧边栏项,请将 customProps 对象添加到任意项中:

{  type: 'doc',  id: 'doc1',  customProps: {    /* 属性 */  }}

复杂侧边栏示例#

来自 Docusaurus 网站的真实示例:

sidebars.js
module.exports = {  docs: [    'introduction',    {      type: 'category',      label: 'Getting Started',      collapsed: false,      items: ['installation', 'configuration', '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',          ],        },        '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',      ],    },  ],};