跳到主要内容
版本：Canary 🚧

侧边栏项目

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

  • Doc: 链接到文档页面，并将其与侧边栏关联
  • Link: 链接到任何内部或外部页面
  • Category: 创建侧边栏项的下拉列表
  • 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
module.exports = {
  mySidebar: [
    // Normal syntax:
    {
      type: "doc",
      id: "doc1", // document ID
      label: "Getting started", // sidebar label
    },

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

如果您使用文档速记或autogenerated边栏，您将失去通过项定义自定义边栏标签的能力。但是，您可以在该文档中使用sidebar_label标记前置事项，它比侧边栏项中的label键具有更高的优先级。类似地，您可以使用sidebar_custom_props为文档页面声明自定义元数据。

备注

doc项设置了一个隐式侧边栏关联。不要将相同的文档分配给多个侧边栏:将类型改为ref。

提示

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

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

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

例子:

sidebars.js
module.exports = {
  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
module.exports = {
  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
module.exports = {
  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
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"],
      },
    ],
  },
};

有了类别链接，点击一个类别可以导航到另一个页面。

提示

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

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

生成的索引页​

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

sidebars.js
module.exports = {
  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
module.exports = {
  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
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时，可以使某些类别可折叠。

默认展开的类别​

默认情况下，可折叠类别是折叠的。如果你想在第一次渲染时展开它们，你可以将collapse设置为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,
        },
      },
    ],
  ],
};
警告

当一个类别有collapse: true但collapsible: false(通过sidebars.js或通过插件配置)时，后者优先，该类别仍然被渲染为展开。

使用速记​

您可以使用速记语法更简洁地表达典型的边栏项，而无需进行太多定制。这有两个部分:文档速记和类别速记。

文档速记​

类型为doc的项可以是一个表示其 ID 的字符串:

sidebars.js
module.exports = {
  sidebar: [
    {
      type: "doc",
      id: "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 = {
  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",
    },
  ],
};

请注意，两个连续的类别简写是如何被压缩成一个包含两个条目的对象的。该语法生成一个侧边栏切片:您不应该将该对象视为一个散装项—该对象被打开，每个条目成为一个单独的项，并且它们与其他项(在本例中为了解更多链接)拼接在一起，形成最终的侧边栏级别。在讨论自动生成侧边栏时，侧边栏切片也很重要。

只要您有一个被简化为一个类别简写的项数组，您就可以省略该封闭数组。

sidebars.js
module.exports = {
  sidebar: [
    {
      "Getting started": ["doc1"],
      Docusaurus: [
        {
          "Basic guides": ["doc2", "doc3"],
          "Advanced guides": ["doc4", "doc5"],
        },
      ],
    },
  ],
};
编辑此页
最后由 wohugb@aliyun.com 于 更新