跳到主要内容

侧边栏项目

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

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

使用 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: '入门', // 侧边栏标签
    },

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

如果使用文档简写或自动生成侧边栏，您将无法通过项目定义自定义侧边栏标签。但是，您可以在文档的 Markdown 前置元数据中使用 sidebar_label，它的优先级高于侧边栏项目中的 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="赞助商" />', // 要渲染的 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: {
    Guides: [
      'creating-pages',
      {
        Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
      },
    ],
  },
};

使用类别链接，单击类别可以导航到其他页面。

提示

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

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

生成索引页面​

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

sidebars.js
export default {
  docs: [
    {
      type: 'category',
      label: '指南',
      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 Guides页面上查看效果。

提示

使用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: '文档',
          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: '文档',
        collapsed: false,
        items: ['markdown-features', 'sidebar', 'versioning'],
      },
    ],
  },
};

类似地，您可以将全局配置options.sidebarCollapsed设置为false。单个collapsed选项在sidebars.js中仍然会优先于此配置。

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://example.com',
    },
  ],
};

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

无论何时，只要您有一个项目数组被简写语法压缩为一个类别简写，您也可以省略该封闭数组。

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