版本：3.8.1

侧边栏项目

我们在上一节的示例中介绍了三种项目类型：doc、category 和 link，它们的用法相当直观。我们将正式介绍它们的 API。还有第四种类型：autogenerated，我们将在后面详细解释。

文档：链接到文档页面，并将其与侧边栏关联
链接：链接到任何内部或外部页面
分类：创建侧边栏项的下拉菜单
自动生成：自动生成侧边栏片段
HTML：在项目位置渲染纯 HTML
*引用：链接到文档页面，但该项不参与导航生成

使用 doc 类型链接到文档页面并将该文档分配给侧边栏

type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut

示例

sidebars.js
export default {
  mySidebar: [
    // Normal syntax:
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },

    // Shorthand syntax:
    'doc2', // document ID
  ],
};

如果您使用文档简写或自动生成的侧边栏，您将无法通过项目定义自定义侧边栏标签。但是，您可以在该文档中使用 sidebar_label Markdown 前置内容，它的优先级高于侧边栏项目中的 label 键。同样，您可以使用 sidebar_custom_props 为文档页面声明自定义元数据。

注意

一个 doc 项目会设置一个隐式侧边栏关联。不要将同一文档分配给多个侧边栏：请改用 ref 类型。

提示

侧边栏自定义属性是将任意文档元数据传播到客户端的有用方式，这样在使用任何获取文档对象的文档相关 Hook 时，您可以获得额外信息。

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

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

示例

sidebars.js
export default {
  myLinksSidebar: [
    // External link
    {
      type: 'link',
      label: 'Facebook', // The link label
      href: 'https://facebook.com', // The external URL
    },

    // Internal link
    {
      type: 'link',
      label: 'Home', // The link label
      href: '/', // The internal path
    },
  ],
};

使用 html 类型在项目的 <li> 标签内渲染自定义 HTML。

这对于插入自定义项目非常有用，例如分隔符、章节标题、广告和图片。

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // Use default menu item styles
  className?: string;
};

示例

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
      defaultStyle: true, // Use the default menu item styling
    },
  ],
};

提示

菜单项已包含在 <li> 标签中，因此如果您的自定义项很简单（例如标题），只需提供一个字符串作为值，并使用 className 属性进行样式设置

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Core concepts',
      className: 'sidebar-title',
    },
  ],
};

使用 category 类型创建侧边栏项的层级结构。

type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  className?: string;
  description?: string;

  // Category options:
  collapsible: boolean; // Set the category to be collapsible
  collapsed: boolean; // Set the category to be initially collapsed or open by default
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

示例

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

提示

当您不需要自定义时，请使用简写语法

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

分类链接

使用分类链接，点击分类可以导航到另一个页面。

提示

使用分类链接来介绍文档分类。

自动生成的分类可以使用_category_.yml文件来声明链接。

生成的索引页

您可以自动生成一个索引页，显示此分类下的所有直接子项。slug 允许您自定义生成页面的路由，默认为 /category/[categoryName]。

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {
        type: 'generated-index',
        title: 'Docusaurus Guides',
        description: 'Learn about the most important Docusaurus concepts!',
        slug: '/category/docusaurus-guides',
        keywords: ['guides'],
        image: '/img/docusaurus.png',
      },
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

在Docusaurus 指南页面查看实际效果。

提示

使用 generated-index 链接作为获取介绍性文档的快捷方式。

文档链接

一个分类可以链接到现有文档。

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {type: 'doc', id: 'introduction'},
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

在i18n 介绍页面查看实际效果。

在文档页面中嵌入生成的索引

您也可以使用 DocCardList 组件将生成的卡片列表嵌入到普通文档页面中。它将显示当前文档父分类下的所有侧边栏项目。

docs/sidebar/index.md
import DocCardList from '@theme/DocCardList';

<DocCardList />

https://:3000

📄️ 侧边栏项目

我们在上一节的示例中介绍了三种项目类型。关于自动生成（autogenerated），我们将在后面详细解释。

📄️ 自动生成

Docusaurus 可以根据您的文件系统结构自动创建侧边栏：每个文件夹创建一个侧边栏分类，每个文件创建一个文档链接。

📄️ 使用多个侧边栏

您可以为希望分组的每组 Markdown 文件创建一个侧边栏。

可折叠分类

我们支持展开/折叠分类的选项。分类默认可折叠，但您可以通过设置 collapsible: false 禁用折叠。

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      items: [
        'creating-pages',
        {
          type: 'category',
          collapsible: false,
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

要默认使所有分类不可折叠，请将 plugin-content-docs 中的 sidebarCollapsible 选项设置为 false

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

注意

sidebars.js 中的选项优先于插件配置，因此即使 sidebarCollapsible 在全局设置为 false，也可以使某些分类可折叠。

默认展开的分类

可折叠分类默认是折叠的。如果您希望它们在首次渲染时展开，可以设置 collapsed 为 false

sidebars.js
export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        type: 'category',
        label: 'Docs',
        collapsed: false,
        items: ['markdown-features', 'sidebar', 'versioning'],
      },
    ],
  },
};

类似于 collapsible，您也可以将全局配置 options.sidebarCollapsed 设置为 false。sidebars.js 中的单独 collapsed 选项仍将优先于此配置。

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

警告

当一个分类设置了 collapsed: true 但 collapsible: false（无论是通过 sidebars.js 还是通过插件配置），后者将优先，分类仍会以展开状态渲染。

使用简写

您可以使用简写语法更简洁地表达不需要太多自定义的典型侧边栏项目。这包括两部分：文档简写和分类简写。

文档简写

类型为 doc 的项目可以简单地是一个表示其 ID 的字符串

完整写法
简写

sidebars.js
export default {
  sidebar: [
    {
      type: 'doc',
      id: 'myDoc',
    },
  ],
};

sidebars.js
export default {
  sidebar: [
    'myDoc',
  ],
};

因此可以将上述示例简化为

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

分类简写

分类项可以由一个对象表示，其键是其标签，值是子项的数组。

完整写法
简写

sidebars.js
export default {
  sidebar: [
    {
      type: 'category',
      label: 'Getting started',
      items: ['doc1', 'doc2'],
    },
  ],
};

sidebars.js
export default {
  sidebar: [
    {
      'Getting started': ['doc1', 'doc2'],
    },
  ],
};

这使我们能够将该示例简化为

sidebars.js
export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
    },
    {
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

此转换后，每个简写对象将仅包含一个条目。现在考虑下面进一步简化的示例

sidebars.js
export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

注意两个连续的分类简写如何被压缩成一个包含两个条目的对象。这种语法生成一个侧边栏片段：您不应将该对象视为一个整体项目——该对象会被解包，每个条目都成为一个单独的项目，并与其余项目（在本例中为“了解更多”链接）拼接在一起，形成最终的侧边栏级别。在讨论自动生成侧边栏时，侧边栏片段也很重要。

无论何时您有一个项目数组被简化为一个分类简写，您也可以省略该外部数组。

之前
之后

sidebars.js
export default {
  sidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: [
        {
          'Basic guides': ['doc2', 'doc3'],
          'Advanced guides': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};

sidebars.js
export default {
  sidebar: {
    'Getting started': ['doc1'],
    Docusaurus: {
      'Basic guides': ['doc2', 'doc3'],
      'Advanced guides': ['doc4', 'doc5'],
    },
  },
};

侧边栏项目

文档：链接到文档

链接：链接到任何页面

HTML：渲染自定义标记

分类：创建层级结构

分类链接

生成的索引页

文档链接

在文档页面中嵌入生成的索引

📄️ 侧边栏项目

📄️ 自动生成

📄️ 使用多个侧边栏

可折叠分类

默认展开的分类

使用简写

文档简写

分类简写

文档：链接到文档​

链接：链接到任何页面​

HTML：渲染自定义标记​

分类：创建层级结构​

分类链接​

生成的索引页​

文档链接​

在文档页面中嵌入生成的索引​

📄️ 侧边栏项目

📄️ 自动生成

📄️ 使用多个侧边栏

可折叠分类​

默认展开的分类​

使用简写​

文档简写​

分类简写​

文档：链接到文档

链接：链接到任何页面

HTML：渲染自定义标记

分类：创建层级结构

分类链接

生成的索引页

文档链接

在文档页面中嵌入生成的索引

可折叠分类

默认展开的分类

使用简写

文档简写

分类简写