版本：2.0.1

侧边栏项目

在上一章节中，我们介绍了三种项目类别：doc、category、link。它们的用途还是很显然的。我们会正式介绍它们的 API。还有第四种类型：autogenerated，我们稍后再详细解释。

Doc: 文档页面的链接，并和侧边栏绑定
Link：内部或外部页面链接
Category：创建侧边栏项下拉菜单
Autogenerated: generate a sidebar slice automatically
HTML：在这个位置渲染纯 HTML
*Ref: link to a doc page, without making the item take part in navigation generation

使用 doc 类型链接至文档页面，并分配链接文档至侧边栏：

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

  // 简写语法
  | string; // 文档 ID 简写

示例：

sidebars.js
module.exports = {
  mySidebar: [
    // 普通语法：
    {
      type: 'doc',
      id: 'doc1', // 文档 ID
      label: 'Getting started', // 侧边栏标签
    },

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

如果你用了文档简写，或者自动生成侧边栏，你就不能通过侧边栏项的定义来自定义侧边栏标签了。然而，你可以在这篇文档中使用 sidebar_label Markdown 前言。它会优先于侧边栏项目中的 label 字段。类似地，你可以用 sidebar_custom_props 来声明文档页面的自定义元数据。

备注

doc 项目会设置隐含侧边栏关联。不要把同一篇文档分配到多个侧边栏里：如果有需要，请使用 ref。

提示

如果想要向客户端传送任意文档元数据，侧边栏自定义属性是个不错的方式，这样你就可以在使用钩子函数时，在返回的文档对象上获得额外的信息了。

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

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

示例：

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

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

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

适用于插入自定义项目，比如分割线、节标题、广告、图片。

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

示例：

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

提示

菜单项目已经被包装在 <li> 标签中了，所以如果你的自定义项目比较简单，比如只是一个标题，那么你只需用一个字符串作为值，然后用 className 属性来提供样式：

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

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

type SidebarItemCategory = {
  type: 'category';
  label: string; // 侧边栏标签文字
  items: SidebarItem[]; // 侧边栏项目列表。
  className?: string;

  // 类别选项
  collapsible: boolean; // 把类别设置为可折叠
  collapsed: boolean; // 把类别设置为默认折叠或打开
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

示例：

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

提示

如果你不需要个性化，可以用简写语法：

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

类别链接

使用类别链接，让点击类别标签可以跳转到另一个页面。

提示

用类别链接来做一组文档的引言。

Autogenerated categories can use the _category_.yml file to declare the link.

生成索引页

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

sidebars.js
module.exports = {
  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
module.exports = {
  docs: [
    {
      type: 'category',
      label: '教程',
      link: {type: 'doc', id: 'introduction'},
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

See it in action on the i18n introduction page.

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

你也可以在普通的文档页面中嵌入生成的卡片列表，只要文档被用作类别索引页。你需要用 DocCardList 组件，配合 useCurrentSidebarCategory 钩子。

a-category-index-page.md
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

在这一节中，我们会介绍下列概念：

<DocCardList items={useCurrentSidebarCategory().items}/>

在侧边栏教程页上看看它的效果。

可折叠分类

我们支持设置展开/折叠分类。下拉菜单默认是可折叠的，但你可以通过 collapsible: false 禁用折叠功能。

sidebars.js
module.exports = {
  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
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsible: false,
        },
      },
    ],
  ],
};

备注

sidebars.js 中的配置优先于插件配置，所以当 sidebarCollapsible 被全局设置为 false 时，仍可以让某些菜单变得可折叠。

默认展开分类

可折叠菜单默认被折叠。如果你希望它们在首次渲染时就是展开状态，你可以将 collapsed 设置为 false：

sidebars.js
module.exports = {
  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
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsed: false,
        },
      },
    ],
  ],
};

注意

当一个菜单同时被设置了 collapsed: true 与 collapsible: false（要么通过 sidebars.js 要么通过插件全局设置），后者将被优先处理，而菜单仍然被渲染为展开状态。

使用简写

对于没有什么个性化设置的普通侧边栏项目，你可以用简写语法更简洁地表达它们。这分为两个部分：文档简写和类别简写。

文档简写

一个 doc 类型的项目可以被简写成一个字符串，代表它的 ID：

完整写法
简写法

sidebars.js
module.exports = {
  sidebar: [
    {
      type: 'doc',
      id: 'myDoc',
    },
  ],
};

sidebars.js
module.exports = {
  sidebar: [
    'myDoc',
  ],
};

所以可以把上面的例子简化成：

sidebars.js
module.exports = {
  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
module.exports = {
  sidebar: [
    {
      type: 'category',
      label: 'Getting started',
      items: ['doc1', 'doc2'],
    },
  ],
};

sidebars.js
module.exports = {
  sidebar: [
    {
      'Getting started': ['doc1', 'doc2'],
    },
  ],
};

这允许我们把上面的例子简化成：

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

在这一步转换之后，每一个简写的对象都会包括恰好一个键值对。现在，考虑下面这个进一步简化的例子：

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

注意到连续的两个类别简写被压缩成了一个有两个键值对的对象。这种语法生成了一个侧边栏切片：你不应该把这个对象看成一个大项目——这个对象会被展开，每一个键值对会变成一个单独的项目，然后这些项目会被和剩下的其他项目拼接在一起（在这里就是 "Learn more" 的链接），组成最终的侧边栏层级。 Sidebar slices are also important when discussing autogenerated sidebars.

只要你有一个项目数组最终被缩减到了一个类别简写，你都可以略去外面的数组方括号。

翻译前
翻译后

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

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

侧边栏项目

Doc - 文档链接

Link - 任意页面链接

HTML - 渲染自定义标记

Category - 创建分类层级

类别链接

生成索引页

文档链接

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

可折叠分类

默认展开分类

使用简写

文档简写

类别简写

侧边栏项目

Doc - 文档链接​

Link - 任意页面链接​

HTML - 渲染自定义标记​

Category - 创建分类层级​

类别链接​

生成索引页​

文档链接​

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

可折叠分类​

默认展开分类​

使用简写​

文档简写​

类别简写​

Doc - 文档链接

Link - 任意页面链接

HTML - 渲染自定义标记

Category - 创建分类层级

类别链接

生成索引页

文档链接

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

可折叠分类

默认展开分类

使用简写

文档简写

类别简写