跳到主要内容
版本：Canary 🚧

侧边栏项目

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

  • Doc: 文档页面的链接，并和侧边栏绑定
  • Link：内部或外部页面链接
  • Category：创建侧边栏项下拉菜单
  • Autogenerated：自动生成侧边栏切片
  • HTML：在这个位置渲染纯 HTML
  • *Ref：链接到文档页面，但项目不会参与生成导航

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

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

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

示例：

sidebars.js
export default {
  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;
  description?: string;
};

示例：

sidebars.js
export default {
  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
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: 'Core concepts',
      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: '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/[类别名]。

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

可折叠分类​

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

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: '教程',
      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 {
  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 {
  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',
    },
  ],
};

注意到连续的两个类别简写被压缩成了一个有两个键值对的对象。 这种语法生成了一个侧边栏切片：你不应该把这个对象看成一个大项目——这个对象会被展开，每一个键值对会变成一个单独的项目，然后这些项目会被和剩下的其他项目拼接在一起（在这里就是 "Learn more" 的链接），组成最终的侧边栏层级。 侧边栏切片的概念在讨论自动生成侧边栏时也很重要。

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

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