跳到主要内容
版本: 3.5.2

侧边栏项目

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

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

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

type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut

示例

sidebars.js
export default {
  mySidebar: [
    // Normal syntax:
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },

    // Shorthand syntax:
    'doc2', // document ID
  ],
};

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

注意

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

提示

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

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

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

示例

sidebars.js
export default {
  myLinksSidebar: [
    // External link
    {
      type: 'link',
      label: 'Facebook', // The link label
      href: 'https://facebook.com', // The external URL
    },

    // Internal link
    {
      type: 'link',
      label: 'Home', // The link label
      href: '/', // The internal path
    },
  ],
};

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

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

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // Use default menu item styles
  className?: string;
};

示例

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
      defaultStyle: true, // Use the default menu item styling
    },
  ],
};
提示

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

sidebars.js
export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Core concepts',
      className: 'sidebar-title',
    },
  ],
};

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

type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  className?: string;
  description?: string;

  // Category options:
  collapsible: boolean; // Set the category to be collapsible
  collapsed: boolean; // Set the category to be initially collapsed or open by default
  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/[categoryName]。

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

提示

使用 generated-index 链接作为获取介绍性文档的快捷方式。

类别可以链接到现有文档。

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

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

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

sidebars.js
export default {
  sidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: [
        {
          'Basic guides': ['doc2', 'doc3'],
          'Advanced guides': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};
编辑此页面
上次更新于 由 Sébastien Lorber 更新