侧边栏项目

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

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

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

type SidebarItemDoc =
  // 常规语法
  | {
      type: 'doc';
      id: string;
      label: string; // 侧边栏标签文本
      className?: string; // 侧边栏标签的类名
      customProps?: Record<string, unknown>; // 自定义属性
    }

  // 简写语法
  | string; // docId 快捷方式

示例：

sidebars.js
export default {
  mySidebar: [
    // 常规语法：
    {
      type: 'doc',
      id: 'doc1', // 文档 ID
      label: '入门', // 侧边栏标签
    },

    // 简写语法：
    'doc2', // 文档 ID
  ],
};

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

备注

doc 项目设置了隐式侧边栏关联。不要将相同的文档分配给多个侧边栏：改为将类型更改为 ref。

提示

侧边栏自定义属性是将任意文档元数据传播到客户端的一种有用方法，因此在使用任何获取文档对象的文档相关钩子时，您可以获得更多信息。

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

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

示例：

sidebars.js
export default {
  myLinksSidebar: [
    // 外部链接
    {
      type: 'link',
      label: 'Facebook', // 链接标签
      href: 'https://facebook.com', // 外部 URL
    },

    // 内部链接
    {
      type: 'link',
      label: '首页', // 链接标签
      href: '/', // 内部路径
    },
  ],
};

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

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

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // 使用默认菜单项样式
  className?: string;
};

示例：

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '<img src="sponsor.png" alt="Sponsor" />', // 要渲染的 HTML
      defaultStyle: true, // 使用默认菜单项样式
    },
  ],
};

提示

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

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '核心概念',
      className: 'sidebar-title',
    },
  ],
};

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

type SidebarItemCategory = {
  type: 'category';
  label: string; // 侧边栏标签文本。
  items: SidebarItem[]; // 侧边栏项目的数组。
  className?: string;
  description?: string;

  // 类别选项：
  collapsible: boolean; // 设置类别是否可折叠
  collapsed: boolean; // 设置类别默认情况下最初是折叠还是展开
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

示例：

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

提示

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

sidebars.js
export default {
  docs: {
    指南: [
      'creating-pages',
      {
        文档: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
      },
    ],
  },
};

类别链接

使用类别链接，单击类别可以将您导航到另一个页面。

提示

使用类别链接来介绍一类文档。

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

生成的索引页面

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

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: '指南',
      link: {
        type: 'generated-index',
        title: 'Docusaurus 指南',
        description: '了解最重要的 Docusaurus 概念！',
        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: '指南',
      link: {type: 'doc', id: 'introduction'},
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

在 i18n 介绍页面上查看其运行情况。

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

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

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

<DocCardList />

http://localhost:3000

📄️ 侧边栏项目

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

📄️ 自动生成

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

📄️ 使用多个侧边栏

您可以为要组合在一起的每个 Markdown 文件集创建一个侧边栏。

可折叠类别

我们支持展开/折叠类别的选项。类别默认情况下是可折叠的，但您可以使用 collapsible: false 禁用折叠。

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: '指南',
      items: [
        'creating-pages',
        {
          type: 'category',
          collapsible: false,
          label: '文档',
          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: {
    指南: [
      'creating-pages',
      {
        type: 'category',
        label: '文档',
        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 的字符串：

Longhand
Shorthand

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

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

因此可以将上面的示例简化为：

sidebars.js
export default {
  mySidebar: [
    {
      type: 'category',
      label: '入门',
      items: [
        'doc1',
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        'doc2',
        'doc3',
      ],
    },
    {
      type: 'link',
      label: '了解更多',
      href: 'https://example.com',
    },
  ],
};

类别简写

类别项目可以用一个对象来表示，该对象的键是其标签，值是子项目的数组。

Longhand
Shorthand

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

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

这允许我们将该示例简化为：

sidebars.js
export default {
  mySidebar: [
    {
      '入门': ['doc1'],
    },
    {
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: '了解更多',
      href: 'https://example.com',
    },
  ],
};

转换后的每个简写对象都将只包含一个条目。现在考虑以下进一步简化的示例：

sidebars.js
export default {
  mySidebar: [
    {
      '入门': ['doc1'],
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: '了解更多',
      href: 'https://example.com',
    },
  ],
};

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

在将项目数组简化为一个类别简写的地方，您也可以省略该封闭数组。

Before
After

sidebars.js
export default {
  sidebar: [
    {
      '入门': ['doc1'],
      Docusaurus: [
        {
          '基础指南': ['doc2', 'doc3'],
          '高级指南': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};

sidebars.js
export default {
  sidebar: {
    '入门': ['doc1'],
    Docusaurus: {
      '基础指南': ['doc2', 'doc3'],
      '高级指南': ['doc4', 'doc5'],
    },
  },
};

侧边栏项目

文档：链接到文档

链接：链接到任何页面

HTML：渲染自定义标记

类别：创建层次结构

类别链接

生成的索引页面

文档链接

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

📄️ 侧边栏项目

📄️ 自动生成

📄️ 使用多个侧边栏

可折叠类别

默认情况下展开的类别

使用简写

文档简写

类别简写

文档：链接到文档​

链接：链接到任何页面​

HTML：渲染自定义标记​

类别：创建层次结构​

类别链接​

生成的索引页面​

文档链接​

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

📄️ 侧边栏项目

📄️ 自动生成

📄️ 使用多个侧边栏

可折叠类别​

默认情况下展开的类别​

使用简写​

文档简写​

类别简写​

文档：链接到文档

链接：链接到任何页面

HTML：渲染自定义标记

类别：创建层次结构

类别链接

生成的索引页面

文档链接

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

可折叠类别

默认情况下展开的类别

使用简写

文档简写

类别简写