侧边栏

创建侧边栏对于以下场景非常有用：

• 将多个相关的文档分组
• 在每个相关文档中显示一个侧边栏
• 提供分页导航，包括"下一页"/"上一页"按钮

要在你的道格龙（Docusaurus）网站上使用侧边栏：

1. 定义一个侧边栏文件，该文件导出一个由侧边栏对象组成的字典。
2. 将其路径直接或通过 @docusaurus/preset-classic 传递给 @docusaurus/plugin-docs 插件。

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js', // 指向你的侧边栏文件
        },
      },
    ],
  ],
};

Node.js 运行环境

侧边栏文件是在 Node.js 环境中运行的。因此，你不能在其中使用或导入浏览器API、React 或 JSX。

本节概述了文档侧边栏的各种功能。在接下来的章节中，我们将更系统地介绍以下概念：

📄️ 侧边栏元素

在上一节的示例中，我们已经介绍过三种项目类型：doc、category 和 link，它们的用法相当直观。接下来，我们将正式介绍它们的 API。此外，还有第四种类型 autogenerated，我们稍后会详细解释。

📄️ 自动生成侧边栏

道格龙（Docusaurus）可以根据你的文件系统结构来自动创建一个侧边栏：每个文件夹创建一个侧边栏分类，每个文件创建一个文档链接。

📄️ 使用多个侧边栏

你可以为每一组希望组合在一起的 Markdown 文件创建一个侧边栏。

默认侧边栏

如果未指定 sidebarPath，道格龙（Docusaurus）会利用 docs 文件夹的文件系统结构，为你自动生成一个侧边栏：

sidebars.js

export default {
  mySidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // 从 docs 文件夹（或 versioned_docs/<version>）生成侧边栏
    },
  ],
};

当然，你也可以明确地定义你的侧边栏。

侧边栏对象

侧边栏是一个由分类、文档链接和其他超链接组成的层级结构。

type Sidebar =
  // 普通语法
  | SidebarItem[]
  // 简写语法
  | {[categoryLabel: string]: SidebarItem[]};

例如：

sidebars.js

export default {
  // `mySidebar` 是此侧边栏的 ID
  mySidebar: [
    {
      type: 'category',
      label: '快速入门',
      items: [
        {
          type: 'doc',
          id: 'doc1', // 文档 ID
        },
      ],
    },
    {
      type: 'category',
      label: '道格龙（Docusaurus）',
      items: [
        {
          type: 'doc',
          id: 'doc2',
        },
        {
          type: 'doc',
          id: 'doc3',
        },
      ],
    },
    {
      type: 'link',
      label: '了解更多',
      href: 'https://aibase.dev',
    },
  ],
};

这是一个导出了一个名为 mySidebar 的侧边栏文件。它有三个顶层项目：两个分类和一个外部链接。在每个分类内部，都有几个文档链接。

一个侧边栏文件可以包含多个侧边栏对象，通过它们的键来识别。

type SidebarsFile = {
  // 键是侧边栏的 ID
  [sidebarID: string]: Sidebar;
};

主题配置

可隐藏的侧边栏

通过启用 themeConfig.docs.sidebar.hideable 选项，你可以让整个侧边栏变得可隐藏，从而允许用户更好地专注于内容。这对于在中等尺寸屏幕（例如平板电脑）上阅读内容时尤其有用。

docusaurus.config.js

export default {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: true,
      },
    },
  },
};

自动折叠侧边栏分类

themeConfig.docs.sidebar.autoCollapseCategories 选项会在展开一个分类时，自动折叠所有同级的其他分类。这避免了用户打开过多分类的烦恼，并帮助他们专注于所选的部分。

docusaurus.config.js

export default {
  themeConfig: {
    docs: {
      sidebar: {
        autoCollapseCategories: true,
      },
    },
  },
};

传递自定义属性

要向侧边栏项目传递自定义属性，只需向任何项目添加可选的 customProps 对象即可。这对于通过 swizzling 渲染侧边栏项目的 React 组件来应用站点定制非常有用。

{
  type: 'doc',
  id: 'doc1',
  // `customProps` 可以包含任何自定义数据
  customProps: {
    badges: ['new', 'green'],
    featured: true,
  },
};

侧边栏面包屑导航

默认情况下，面包屑导航会使用当前页面的"侧边栏路径"在页面顶部渲染。

可以通过插件选项禁用此行为：

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          breadcrumbs: false, // 禁用面包屑导航
        },
      },
    ],
  ],
};

复杂侧边栏示例

一个来自道格龙（Docusaurus）网站的真实示例：

sidebars.js

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
  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/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/toc',
            'guides/markdown-features/assets',
            'guides/markdown-features/links',
            'guides/markdown-features/plugins',
            'guides/markdown-features/math-equations',
            'guides/markdown-features/diagrams',
            'guides/markdown-features/head-metadata',
          ],
        },
        'styling-layout',
        'swizzling',
        '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/ssg',
        'advanced/client',
      ],
    },
    {
      type: 'category',
      label: 'Upgrading',
      link: {
        type: 'doc',
        id: 'migration/index',
      },
      items: [
        'migration/v3',
        {
          type: 'category',
          label: 'To Docusaurus v2',
          items: [
            'migration/v2/migration-overview',
            'migration/v2/migration-automated',
            'migration/v2/migration-manual',
            'migration/v2/migration-versioned-sites',
            'migration/v2/migration-translated-sites',
          ],
        },
      ],
    },
  ],
  api: [
    'cli',
    'docusaurus-core',
    {
      type: 'autogenerated',
      dirName: 'api',
    },
  ],
};
export default sidebars;