跳到主要内容

侧边栏元素

在上一节的示例中，我们已经介绍过三种项目类型：doc、category 和 link，它们的用法相当直观。接下来，我们将正式介绍它们的 API。此外，还有第四种类型 autogenerated，我们稍后会详细解释。

使用 doc 类型可以链接到一个文档页面，并将其分配给一个侧边栏：

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

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

例如：

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

    // 简写语法：
    'doc2', // 直接使用文档 ID
  ],
};

如果你使用文档简写或自动生成的侧边栏，你将无法通过项目定义来定制侧边栏标签。但是，你可以在该文档中使用 sidebar_label Markdown 头部元数据，它的优先级高于侧边栏项目中的 label 键。类似地，你可以使用 sidebar_custom_props 为文档页面声明自定义元数据。

备注

一个 doc 项目会建立一个隐式的侧边栏关联。不要将同一个文档分配给多个侧边栏：应该改用 ref 类型。

提示

侧边栏的自定义 属性 是一个向客户端传播任意文档元数据的有效方式，这样当使用任何获取文档对象的、与文档相关的 hook 时，你就可以获得额外的信息。

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

type SidebarItemLink = {
  type: 'link';
  label: string; // 链接的标签
  href: string; // 链接的 URL
  className?: string; // CSS 类名
  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; // 要渲染的 HTML 字符串
  defaultStyle?: boolean; // 是否使用默认的菜单项样式
  className?: string; // CSS 类名
};

例如：

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

菜单项已经被一个 <li> 标签包裹，所以如果你的自定义项很简单（例如一个标题），只需提供一个字符串作为 value，然后使用 className 属性来为其设置样式即可：

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

使用 category 类型可以创建一个侧边栏项目的层级结构。

type SidebarItemCategory = {
  type: 'category';
  label: string; // 侧边栏显示的标签文本
  items: SidebarItem[]; // 侧边栏项目的数组
  className?: string; // CSS 类名
  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/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 介绍页面看到实际效果。

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

你也可以使用 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: '文档',
          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 的字符串：

sidebars.js
export default {
  sidebar: [
    {
      type: 'doc',
      id: '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',
    },
  ],
};

分类简写​

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

sidebars.js
export default {
  sidebar: [
    {
      type: 'category',
      label: '快速入门',
      items: ['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://aibase.dev',
    },
  ],
};

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

无论何时，如果一个项目数组被简化为只包含一个分类简写，你都可以省略外层的数组。

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