侧边栏项目
¥Sidebar items
我们在上一节的例子中介绍了三种类型的 item 类型：doc、category、link，其用法相当直观。我们将正式介绍他们的 API。还有第四种：autogenerated，我们稍后会详细解释。
¥We have introduced three types of item types in the example in the previous section: doc, category, and link, whose usages are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: autogenerated, which we will explain in detail later.
-
文档：链接到文档页面，将其与侧边栏关联
¥Doc: link to a doc page, associating it with the sidebar
-
关联：链接到任何内部或外部页面
¥Link: link to any internal or external page
-
类别：创建侧边栏项目的下拉菜单
¥Category: creates a dropdown of sidebar items
-
自动生成：自动生成侧边栏切片
¥Autogenerated: generate a sidebar slice automatically
-
HTML：在项目的位置渲染纯 HTML
¥HTML: renders pure HTML in the item's position
-
*参考：链接到文档页面，而不使该项目参与导航生成
¥*Ref: link to a doc page, without making the item take part in navigation generation
文档：链接到文档
¥Doc: link to a doc
使用 doc 类型链接到文档页面并将该文档分配到侧边栏：
¥Use the doc type to link to a doc page and assign that doc to a sidebar:
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
示例：
¥Example:
export default {
mySidebar: [
// Normal syntax:
{
type: 'doc',
id: 'doc1', // document ID
label: 'Getting started', // sidebar label
},
// Shorthand syntax:
'doc2', // document ID
],
};
如果你使用 doc 简写或 autogenerated 侧边栏，你将无法通过项目定义自定义侧边栏标签。但是，你可以在该文档中使用 sidebar_label Markdown 前面的内容，它的优先级高于侧边栏项目中的 label 键。同样，你可以使用 sidebar_custom_props 声明文档页面的自定义元数据。
¥If you use the doc shorthand or autogenerated sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the sidebar_label Markdown front matter within that doc, which has higher precedence over the label key in the sidebar item. Similarly, you can use sidebar_custom_props to declare custom metadata for a doc page.
doc 项设置 隐式侧边栏关联。不要将同一个文档分配给多个侧边栏：将类型更改为 ref。
¥A doc item sets an implicit sidebar association. Don't assign the same doc to multiple sidebars: change the type to ref instead.
侧边栏自定义属性是将任意文档元数据传播到客户端的有用方法，因此你可以在使用任何与文档相关的钩子来获取文档对象时获取附加信息。
¥Sidebar custom props is a useful way to propagate arbitrary doc metadata to the client side, so you can get additional information when using any doc-related hook that fetches a doc object.
链接：链接到任何页面
¥Link: link to any page
使用 link 类型链接到任何非文档页面（内部或外部）。
¥Use the link type to link to any page (internal or external) that is not a doc.
type SidebarItemLink = {
type: 'link';
label: string;
href: string;
className?: string;
description?: string;
};
示例：
¥Example:
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:渲染自定义标记
¥HTML: render custom markup
使用 html 类型在项目的 <li> 标记内渲染自定义 HTML。
¥Use the html type to render custom HTML within the item's <li> tag.
这对于插入自定义项目（例如分隔符、章节标题、广告和图片）非常有用。
¥This can be useful for inserting custom items such as dividers, section titles, ads, and images.
type SidebarItemHtml = {
type: 'html';
value: string;
defaultStyle?: boolean; // Use default menu item styles
className?: string;
};
示例：
¥Example:
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 属性对其进行样式设置：
¥The menu item is already wrapped in an <li> tag, so if your custom item is simple, such as a title, just supply a string as the value and use the className property to style it:
export default {
myHtmlSidebar: [
{
type: 'html',
value: 'Core concepts',
className: 'sidebar-title',
},
],
};
类别：创建层次结构
¥Category: create a hierarchy
使用 category 类型创建侧边栏项目的层次结构。
¥Use the category type to create a hierarchy of sidebar items.
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;
};
示例：
¥Example:
export default {
docs: [
{
type: 'category',
label: 'Guides',
collapsible: true,
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
当你不需要自定义时使用 简写语法：
¥Use the shorthand syntax when you don't need customizations:
export default {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
类别链接
¥Category links
通过类别链接，单击类别可以将你导航到另一个页面。
¥With category links, clicking on a category can navigate you to another page.
使用类别链接来介绍文档类别。
¥Use category links to introduce a category of documents.
自动生成的类别可以使用 _category_.yml 文件来声明链接。
¥Autogenerated categories can use the _category_.yml file to declare the link.
生成的索引页
¥Generated index page
你可以自动生成一个索引页，显示该类别的所有直接子项。slug 允许你自定义生成页面的路由，默认为 /category/[categoryName]。
¥You can auto-generate an index page that displays all the direct children of this category. The slug allows you to customize the generated page's route, which defaults to /category/[categoryName].
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 指南页面 上的实际应用。
¥See it in action on the Docusaurus Guides page.
使用 generated-index 链接作为获取介绍性文档的快速方法。
¥Use generated-index links as a quick way to get an introductory document.
文档链接
¥Doc link
类别可以链接到现有文档。
¥A category can link to an existing document.
export default {
docs: [
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'introduction'},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
查看它在 i18n 介绍页面 上的实际应用。
¥See it in action on the i18n introduction page.
在文档页面中嵌入生成的索引
¥Embedding generated index in doc page
你也可以使用 DocCardList 组件将生成的卡片列表嵌入到普通文档页面中。它将显示当前文档父类别的所有侧边栏项目。
¥You can embed the generated cards list in a normal doc page as well with the DocCardList component. It will display all the sidebar items of the parent category of the current document.
import DocCardList from '@theme/DocCardList';
<DocCardList />
可折叠类别
¥Collapsible categories
我们支持展开/折叠类别的选项。默认情况下，类别是可折叠的，但你可以使用 collapsible: false 禁用折叠。
¥We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with collapsible: false.
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：
¥To make all categories non-collapsible by default, set the sidebarCollapsible option in plugin-content-docs to false:
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsible: false,
},
},
],
],
};
sidebars.js 中的选项优先于插件配置，因此当 sidebarCollapsible 全局设置为 false 时，可以使某些类别可折叠。
¥The option in sidebars.js takes precedence over plugin configuration, so it is possible to make certain categories collapsible when sidebarCollapsible is set to false globally.
默认扩展类别
¥Expanded categories by default
默认情况下，可折叠类别是折叠的。如果你希望它们在第一次渲染时展开，你可以将 collapsed 设置为 false：
¥Collapsible categories are collapsed by default. If you want them to be expanded on the first render, you can set collapsed to false:
export default {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};
与 collapsible 类似，你也可以将全局配置 options.sidebarCollapsed 设置为 false。sidebars.js 中的各个 collapsed 选项仍优先于此配置。
¥Similar to collapsible, you can also set the global configuration options.sidebarCollapsed to false. Individual collapsed options in sidebars.js will still take precedence over this configuration.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsed: false,
},
},
],
],
};
当类别具有 collapsed: true 但有 collapsible: false（通过 sidebars.js 或通过插件配置）时，后者优先，类别仍渲染为展开状态。
¥When a category has collapsed: true but collapsible: false (either through sidebars.js or through plugin configuration), the latter takes precedence and the category is still rendered as expanded.
使用简写
¥Using shorthands
你可以使用速记语法更简洁地表达典型的侧边栏项目，而无需进行太多自定义。这有两个部分：文档速记 和 类别简写。
¥You can express typical sidebar items without much customization more concisely with shorthand syntaxes. There are two parts to this: doc shorthand and category shorthand.
文档速记
¥Doc shorthand
类型为 doc 的项目可以只是表示其 ID 的字符串：
¥An item with type doc can be simply a string representing its ID:
- Longhand
- Shorthand
export default {
sidebar: [
{
type: 'doc',
id: 'myDoc',
},
],
};
export default {
sidebar: [
'myDoc',
],
};
因此可以将上面的示例简化为：
¥So it's possible to simplify the example above to:
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',
},
],
};
类别简写
¥Category shorthand
类别项可以用一个对象来表示，该对象的键是其标签，值是子项数组。
¥A category item can be represented by an object whose key is its label, and the value is an array of subitems.
- Longhand
- Shorthand
export default {
sidebar: [
{
type: 'category',
label: 'Getting started',
items: ['doc1', 'doc2'],
},
],
};
export default {
sidebar: [
{
'Getting started': ['doc1', 'doc2'],
},
],
};
这使我们能够将该示例简化为：
¥This permits us to simplify that example to:
export default {
mySidebar: [
{
'Getting started': ['doc1'],
},
{
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
此转换后的每个速记对象将只包含一个条目。现在考虑下面进一步简化的示例：
¥Each shorthand object after this transformation will contain exactly one entry. Now consider the further simplified example below:
export default {
mySidebar: [
{
'Getting started': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
请注意两个连续的类别简写如何被压缩为具有两个条目的一个对象。此语法生成侧边栏切片：你不应该将该对象视为一个散装项目 - 该对象已展开，每个条目都成为一个单独的项目，并且它们与其余项目（在本例中为 "了解更多" 链接）拼接在一起以形成最终的侧边栏级别 。在讨论 自动生成的侧边栏 时，侧边栏切片也很重要。
¥Note how the two consecutive category shorthands are compressed into one object with two entries. This syntax generates a sidebar slice: you shouldn't see that object as one bulk item—this object is unwrapped, with each entry becoming a separate item, and they spliced together with the rest of the items (in this case, the "Learn more" link) to form the final sidebar level. Sidebar slices are also important when discussing autogenerated sidebars.
只要你将一组项目简化为一个类别简写，你也可以省略该封闭数组。
¥Wherever you have an array of items that is reduced to one category shorthand, you can omit that enclosing array as well.
- Before
- After
export default {
sidebar: [
{
'Getting started': ['doc1'],
Docusaurus: [
{
'Basic guides': ['doc2', 'doc3'],
'Advanced guides': ['doc4', 'doc5'],
},
],
},
],
};
export default {
sidebar: {
'Getting started': ['doc1'],
Docusaurus: {
'Basic guides': ['doc2', 'doc3'],
'Advanced guides': ['doc4', 'doc5'],
},
},
};