侧边栏项目
在上一章节中，我们介绍了三种项目类别：doc、category、link。它们的用途还是很显然的。 我们会正式介绍它们的 API。 还有第四种类型：autogenerated，我们稍后再详细解释。
- Doc: 文档页面的链接，并和侧边栏绑定
- Link：内部或外部页面链接
- Category：创建侧边栏项下拉菜单
- Autogenerated: generate a sidebar slice automatically
- HTML：在这个位置渲染纯 HTML
- *Ref: link to a doc page, without making the item take part in navigation generation
Doc - 文档链接
使用 doc 类型链接至文档页面，并分配链接文档至侧边栏：
type SidebarItemDoc =
// 普通语法
| {
type: 'doc';
id: string;
label: string; // 侧边栏标签文本
className?: string; // 侧边栏标签类名
customProps?: Record<string, unknown>; // 自定义属性
}
// 简写语法
| string; // 文档 ID 简写
示例：
module.exports = {
mySidebar: [
// 普通语法：
{
type: 'doc',
id: 'doc1', // 文档 ID
label: 'Getting started', // 侧边栏标签
},
// 简写语法：
'doc2', // 文档 ID
],
};
如果你用了文档简写，或者自动生成侧边栏，你就不能通过侧边栏项的定义来自定义侧边栏标签了。 然而，你可以在这篇文档中使用 sidebar_label Markdown 前言。它会优先于侧边栏项目中的 label 字段。 类似地，你可以用 sidebar_custom_props 来声明文档页面的自定义元数据。
doc 项目会设置隐含侧边栏关联。 不要把同一篇文档分配到多个侧边栏里：如果有需要，请使用 ref。
如果想要向客户端传送任意文档元数据，侧边栏自定义属性是个不错的方式，这样你就可以在使用钩子函数时，在返回的文档对象上获得额外的信息了。
Link - 任意页面链接
使用 link 类型链接到任何非文档的页面（内部或外部链接） 。
type SidebarItemLink = {
type: 'link';
label: string;
href: string;
className?: string;
};
示例：
module.exports = {
myLinksSidebar: [
// 外部链接
{
type: 'link',
label: 'Facebook', // 链接标签
href: 'https://facebook.com', // 外部 URL
},
// 内部链接
{
type: 'link',
label: 'Home', // 链接标签
href: '/', // 内部路径
},
],
};
HTML - 渲染自定义标记
使用 html 类型在项目的 <li> 标签中渲染自定义 HTML。
适用于插入自定义项目，比如分割线、节标题、广告、图片。
type SidebarItemHtml = {
type: 'html';
value: string;
defaultStyle?: boolean; // 使用默认的菜单项目样式
className?: string;
};
示例：
module.exports = {
myHtmlSidebar: [
{
type: 'html',
value: '<img src="sponsor.png" alt="Sponsor" />', // 要渲染的 HTML
defaultStyle: true, // 使用默认的菜单项目样式
},
],
};
菜单项目已经被包装在 <li> 标签中了，所以如果你的自定义项目比较简单，比如只是一个标题，那么你只需用一个字符串作为值，然后用 className 属性来提供样式：
module.exports = {
myHtmlSidebar: [
{
type: 'html',
value: '核心概念',
className: 'sidebar-title',
},
],
};
Category - 创建分类层级
使用 category 类型创建侧边栏项的层次结构。
type SidebarItemCategory = {
type: 'category';
label: string; // 侧边栏标签文字
items: SidebarItem[]; // 侧边栏项目列表。
className?: string;
// 类别选项
collapsible: boolean; // 把类别设置为可折叠
collapsed: boolean; // 把类别设置为默认折叠或打开
link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};
示例：
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
collapsible: true,
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
如果你不需要个性化，可以用简写语法：
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
类别链接
使用类别链接，让点击类别标签可以跳转到另一个页面。
用类别链接来做一组文档的引言。
Autogenerated categories can use the _category_.yml file to declare the link.
生成索引页
你可以自动生成一个索引页，显示此类别的所有直接子项。 slug 允许你自定义生成页面的路径，默认为 /category/[类别名]。
module.exports = {
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 链接来快速生成介绍文档。
文档链接
类别链接可以指向现有的文档。
module.exports = {
docs: [
{
type: 'category',
label: '教程',
link: {type: 'doc', id: 'introduction'},
items: ['pages', 'docs', 'blog', 'search'],
},
],
};
See it in action on the i18n introduction page.
在文档页面中嵌入生成索引
你可以通过 DocCardList 组件，在普通的文档页中也嵌入自动生成的卡片列表。 它会显示当前文档所属类别的所有侧边栏项目。
import DocCardList from '@theme/DocCardList';
<DocCardList />
可折叠分类
我们支持设置展开/折叠分类。 下拉菜单默认是可折叠的，但你可以通过 collapsible: false 禁用折叠功能。
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：
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsible: false,
},
},
],
],
};
sidebars.js 中的配置优先于插件配置，所以当 sidebarCollapsible 被全局设置为 false 时，仍可以让某些菜单变得可折叠。
默认展开分类
可折叠菜单默认被折叠。 如果你希望它们在首次渲染时就是展开状态，你可以将 collapsed 设置为 false：
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};
与 collapsible 类似，你也可以在全局配置中将 options.sidebarCollapsed 设置为 false。 sidebars.js 中的 collapsed 选项仍会覆盖这一设置。
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarCollapsed: false,
},
},
],
],
};
当一个菜单同时被设置了 collapsed: true 与 collapsible: false（要么通过 sidebars.js 要么通过插件全局设置），后者将被优先处理，而菜单仍然被渲染为展开状态。
使用简写
对于没有什么个性化设置的普通侧边栏项目，你可以用简写语法更简洁地表达它们。 这分为两个部分：文档简写和类别简写。
文档简写
一个 doc 类型的项目可以被简写成一个字符串，代表它的 ID：
- 完整写法
- 简写法
module.exports = {
sidebar: [
{
type: 'doc',
id: 'myDoc',
},
],
};
module.exports = {
sidebar: [
'myDoc',
],
};
所以可以把上面的例子简化成：
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',
},
],
};
类别简写
一个类别可以用一个对象代替，对象的键是它的标签，值是它的子项目的列表。
- 完整写法
- 简写法
module.exports = {
sidebar: [
{
type: 'category',
label: 'Getting started',
items: ['doc1', 'doc2'],
},
],
};
module.exports = {
sidebar: [
{
'Getting started': ['doc1', 'doc2'],
},
],
};
这允许我们把上面的例子简化成：
module.exports = {
mySidebar: [
{
'Getting started': ['doc1'],
},
{
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
在这一步转换之后，每一个简写的对象都会包括恰好一个键值对。 现在，考虑下面这个进一步简化的例子：
module.exports = {
mySidebar: [
{
'Getting started': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
注意到连续的两个类别简写被压缩成了一个有两个键值对的对象。 这种语法生成了一个侧边栏切片：你不应该把这个对象看成一个大项目——这个对象会被展开，每一个键值对会变成一个单独的项目，然后这些项目会被和剩下的其他项目拼接在一起（在这里就是 "Learn more" 的链接），组成最终的侧边栏层级。 Sidebar slices are also important when discussing autogenerated sidebars.
只要你有一个项目数组最终被缩减到了一个类别简写，你都可以略去外面的数组方括号。
- 翻译前
- 翻译后
module.exports = {
sidebar: [
{
'Getting started': ['doc1'],
Docusaurus: [
{
'Basic guides': ['doc2', 'doc3'],
'Advanced guides': ['doc4', 'doc5'],
},
],
},
],
};
module.exports = {
sidebar: {
'Getting started': ['doc1'],
Docusaurus: {
'Basic guides': ['doc2', 'doc3'],
'Advanced guides': ['doc4', 'doc5'],
},
},
};