跳到主要内容
版本:Canary 🚧

侧边栏项目

在上一章节中,我们介绍了三种项目类别:doccategorylink。它们的用途还是很显然的。 我们会正式介绍它们的 API。 还有第四种类型:autogenerated,我们稍后再详细解释。

  • Doc: 文档页面的链接,并和侧边栏绑定
  • Link:内部或外部页面链接
  • Category:创建侧边栏项下拉菜单
  • Autogenerated:自动生成侧边栏切片
  • HTML:在这个位置渲染纯 HTML
  • *Ref:链接到文档页面,但项目不会参与生成导航

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

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

如果你用了文档简写,或者自动生成侧边栏,你就不能通过侧边栏项的定义来自定义侧边栏标签了。 然而,你可以在这篇文档中使用 sidebar_label Markdown 前言。它会优先于侧边栏项目中的 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: 'Home', // 链接标签
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="Sponsor" />', // 要渲染的 HTML
defaultStyle: true, // 使用默认的菜单项目样式
},
],
};
提示

菜单项目已经被包装在 <li> 标签中了,所以如果你的自定义项目比较简单,比如只是一个标题,那么你只需用一个字符串作为值,然后用 className 属性来提供样式:

sidebars.js
export default {
myHtmlSidebar: [
{
type: 'html',
value: 'Core concepts',
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: '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/[类别名]

sidebars.js
export default {
docs: [
{
type: 'category',
label: '教程',
link: {
type: 'generated-index',
title: 'Docusaurus 教程',
description: '学习最重要的 Docusaurus 概念!',
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: '教程',
link: {type: 'doc', id: 'introduction'},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};

i18n 介绍页上看看它的效果。

在文档页面中嵌入生成索引

你可以通过 DocCardList 组件,在普通的文档页中也嵌入自动生成的卡片列表。 它会显示当前文档所属类别的所有侧边栏项目。

docs/sidebar/index.md
import DocCardList from '@theme/DocCardList';

<DocCardList />

可折叠分类

我们支持设置展开/折叠分类。 下拉菜单默认是可折叠的,但你可以通过 collapsible: false 禁用折叠功能。

sidebars.js
export default {
docs: [
{
type: 'category',
label: '教程',
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 设置为 falsesidebars.js 中的 collapsed 选项仍会覆盖这一设置。

docusaurus.config.js
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsed: false,
},
},
],
],
};
警告

当一个菜单同时被设置了 collapsed: truecollapsible: 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',
},
],
};

注意到连续的两个类别简写被压缩成了一个有两个键值对的对象。 这种语法生成了一个侧边栏切片:你不应该把这个对象看成一个大项目——这个对象会被展开,每一个键值对会变成一个单独的项目,然后这些项目会被和剩下的其他项目拼接在一起(在这里就是 "Learn more" 的链接),组成最终的侧边栏层级。 侧边栏切片的概念在讨论自动生成侧边栏时也很重要。

只要你有一个项目数组最终被缩减到了一个类别简写,你都可以略去外面的数组方括号。

sidebars.js
export default {
sidebar: [
{
'Getting started': ['doc1'],
Docusaurus: [
{
'Basic guides': ['doc2', 'doc3'],
'Advanced guides': ['doc4', 'doc5'],
},
],
},
],
};