侧边栏

¥Sidebar

创建侧边栏有助于：

¥Creating a sidebar is useful to:

• 将多个相关文档分组

  ¥Group multiple related documents

• 在每个文档上显示侧边栏

  ¥Display a sidebar on each of those documents

• 提供分页导航，带有下一个/上一个按钮

  ¥Provide paginated navigation, with next/previous button

要在 Docusaurus 网站上使用侧边栏：

¥To use sidebars on your Docusaurus site:

1. 定义一个导出 侧边栏对象 字典的侧边栏文件。

   ¥Define a sidebars file that exports a dictionary of sidebar objects.

2. 将其路径直接或通过 @docusaurus/preset-classic 传递给 @docusaurus/plugin-docs 插件。

   ¥Pass its path to the @docusaurus/plugin-docs plugin directly or via @docusaurus/preset-classic.

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
      },
    ],
  ],
};

Node.js 运行时

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

¥The sidebars file is run with Node.js. You can't use or import browsers APIs, React or JSX in it.

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

¥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:

📄️ 侧边栏项目

sidebar-items}

📄️ 自动生成

autogenerated}

📄️ 使用多个侧边栏

using-multiple-sidebars}

默认侧边栏

¥Default sidebar

如果未指定 sidebarPath，Docusaurus 自动生成侧边栏 会为你提供，通过使用 docs 文件夹的文件系统结构：

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

sidebars.js

export default {
  mySidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
    },
  ],
};

你还可以明确定义侧边栏。

¥You can also define your sidebars explicitly.

侧边栏对象

¥Sidebar object

侧边栏的关键是类别、文档链接和其他超链接的层次结构。

¥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[]};

例如：

¥For example:

sidebars.js

export default {
  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',
    },
  ],
};

这是一个侧边栏文件，导出一个侧边栏，名为 mySidebar。它具有三个顶层项目：两个类别和一个外部链接。每个类别中都有一些文档链接。

¥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;
};

主题配置

¥Theme configuration

可隐藏侧边栏

¥Hideable sidebar

通过启用 themeConfig.docs.sidebar.hideable 选项，你可以使整个侧边栏可隐藏，让用户更好地关注内容。当在中型屏幕（例如平板电脑）上消费内容时，这尤其有用。

¥By enabling the themeConfig.docs.sidebar.hideable 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

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

自动折叠侧边栏类别

¥Auto-collapse sidebar categories

themeConfig.docs.sidebar.autoCollapseCategories 选项将在展开一个类别时折叠所有同级类别。这可以避免用户打开太多类别，并帮助他们专注于所选部分。

¥The themeConfig.docs.sidebar.autoCollapseCategories 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

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

传递自定义属性

¥Passing custom props

要将自定义属性传递到侧边栏项目，请将可选的 customProps 对象添加到任何项目。这对于通过混合 React 组件渲染侧边栏项目来应用站点自定义非常有用。

¥To pass in custom props to a sidebar item, add the optional customProps object to any of the items. This is useful to apply site customizations by swizzling React components rendering sidebar items.

{
  type: 'doc',
  id: 'doc1',
  customProps: {
    badges: ['new', 'green'],
    featured: true,
  },
};

侧边栏面包屑

¥Sidebar Breadcrumbs

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

¥By default, breadcrumbs are rendered at the top, using the "sidebar path" of the current page.

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

¥This behavior can be disabled with plugin options:

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          breadcrumbs: false,
        },
      },
    ],
  ],
};

复杂侧边栏示例

¥Complex sidebars example

来自 Docusaurus 网站的真实示例：

¥A real-world example from the Docusaurus site:

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;