跳到主要内容
版本：Canary 🚧

侧边栏

创建侧边栏用于:

  • 对多个相关文档进行分组
  • 在每个文档上显示侧边栏
  • 提供分页导航，带有上一/下一按钮

在你的 Docusaurus 网站上使用侧边栏:

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

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

默认的侧边栏​

如果sidebarPath未指定，Docusaurus自动生成一个侧边栏，通过使用docs文件夹的文件系统结构:

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

还可以显式地定义侧边栏。

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

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",
    },
  ],
};

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

侧边栏文件可以包含多个侧边栏对象，由它们的对象键来标识。

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

主题配置​

可隐藏侧边栏​

通过启用themeConfig.docs.sidebar.hideable选项，您可以使整个侧边栏可隐藏，从而使用户能够更好地关注内容。当内容是在中等大小的屏幕上消费时(例如平板电脑)，这尤其有用。

docusaurus.config.js
module.exports = {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: true,
      },
    },
  },
};

自动折叠侧边栏类别​

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

docusaurus.config.js
module.exports = {
  themeConfig: {
    docs: {
      sidebar: {
        autoCollapseCategories: true,
      },
    },
  },
};

传递自定义属性​

要将自定义属性传递给侧边栏项，请向任何项添加可选的customProps对象。这对于通过使 React 组件呈现侧边栏项来应用站点自定义非常有用。

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

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

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

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

复杂边栏示例​

一个来自 Docusaurus 网站的真实例子:

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/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: '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;
编辑此页
最后由 wohugb@aliyun.com 于 更新