侧边栏
创建侧边栏可以：
- Group multiple related documents into an ordered tree
- Display a common sidebar on each of those documents
- 提供下一篇/上一篇按钮的分页导航
要在你的 Docusaurus 网站上使用侧边栏，只需两步：
- 定义一个侧边栏文件，由它导出一个包含 sidebar objects 的字典。
- 直接将这个对象传入
@docusaurus/plugin-docs，或者通过@docusaurus/preset-classic传入。
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};
侧边栏文件通过 Node.js 运行。 您不能在其中使用或导入浏览器 APIs、React 或 JSX。
这个章节是文档侧边栏功能的一个总览。 在接下来的章节中，我们会系统地介绍下列概念：
📄️ 侧边栏项目
The sidebar supports various item types:
📄️ 自动生成侧边栏
Docusaurus 可以根据你的文件系统结构自动生成侧边栏：每个文件夹会生成一个类别，每个文件会生成一个文档链接。
📄️ 使用多个侧边栏
你可以为每组想要分类到一起的 Markdown 文件创建一个侧边栏。
默认侧边栏
如果没有给定 sidebarPath，Docusaurus 会根据 docs 文件夹的结构自动生成侧边栏。
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // 从 docs 文件夹 (或 versioned_docs/<version>) 生成侧边栏
},
],
};
你也可以显式定义你的侧边栏。
侧边栏对象
侧边栏简单来说就是由一些类别、文档链接、其他超链接组成的层级结构。
type Sidebar =
// 普通语法
| SidebarItem[]
// 简写语法
| {[categoryLabel: string]: SidebarItem[]};
举个例子：
export default {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};
这是一个导出了一个叫做 mySidebar 的侧边栏的文件。 它有三个顶层项目：两个类别和一个外部链接。 每个类别内部都有几个文档链接。
一个侧边栏文件可以包含多个侧边栏对象，这些对象由其对象键标识。
type SidebarsFile = {
[sidebarID: string]: Sidebar;
};
主题配置
可隐藏侧边栏
启用 themeConfig.docs.sidebar.hideable 选项后，你可以使整个侧边栏变得可隐藏，让用户能够更好地关注内容。 这对于中等屏幕大小（如平板）的读者来说格外有用。
export default {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};
自动折叠侧边栏类别
themeConfig.docs.sidebar.autoCollapseCategories 选项会在扩展一个类别时折叠所有的同级类别。 这能让用户免于打开过多的菜单，帮助他们关注选定的部分。
export default {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};
Passing CSS classes
To pass CSS classes to a sidebar item, add the optional className attribute to any of the items. This is useful to apply visual customizations to specific sidebar items.
{
type: 'doc',
id: 'doc1',
className: 'sidebar-item--highlighted',
};
传递自定义属性
要将自定义属性传递给侧边栏项目，请使用 customProps 字段。 这对于通过混合 React 组件呈现侧边栏项来应用网站自定义功能非常有用。
{
type: 'doc',
id: 'doc1',
customProps: {
badges: ['new', 'green'],
featured: true,
},
};
Passing a unique key
Passing a unique key attribute can help uniquely identify a sidebar item. Sometimes other attributes (such as label) are not enough to distinguish two sidebar items from each other.
{
type: 'category',
label: 'API', // You may have multiple categories with this widespread label
key: 'api-for-feature-1', // and now, they can be uniquely identified
};
Docusaurus only uses the key attribute to generate unique i18n translation keys. When a translation key conflict happens (issue), Docusaurus will tell you to apply a key to distinguish sidebar items.
Alternatively, you may have your own reasons for using the key attribute that will be passed to the respective sidebar item React components.
侧边栏面包屑导航
面包屑导航默认会在页面顶端渲染。它用的是当前页面的「侧边栏路径」。
这个行为可以用插件选项禁用：
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};
复杂侧边栏示例
来自 Docusaurus 网站的真实例子：
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
link: {
type: 'generated-index',
},
collapsed: false,
items: [
'installation',
'configuration',
'playground',
'typescript-support',
],
},
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Docusaurus Guides',
description:
"Let's learn about the most important Docusaurus concepts!",
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: [
'guides/creating-pages',
{
type: 'category',
label: 'Docs',
link: {
type: 'doc',
id: 'guides/docs/introduction',
},
items: [
'guides/docs/create-doc',
{
type: 'category',
label: 'Sidebar',
link: {
type: 'doc',
id: 'guides/docs/sidebar/index',
},
items: [
'guides/docs/sidebar/items',
'guides/docs/sidebar/autogenerated',
'guides/docs/sidebar/multiple-sidebars',
],
},
'guides/docs/versioning',
'guides/docs/multi-instance',
],
},
'blog',
{
type: 'category',
label: 'Markdown Features',
link: {
type: 'doc',
id: 'guides/markdown-features/introduction',
},
items: [
'guides/markdown-features/react',
'guides/markdown-features/tabs',
'guides/markdown-features/code-blocks',
'guides/markdown-features/admonitions',
'guides/markdown-features/toc',
'guides/markdown-features/assets',
'guides/markdown-features/links',
'guides/markdown-features/plugins',
'guides/markdown-features/math-equations',
'guides/markdown-features/diagrams',
'guides/markdown-features/head-metadata',
],
},
'styling-layout',
'swizzling',
'static-assets',
'search',
'browser-support',
'seo',
'using-plugins',
'deployment',
{
type: 'category',
label: 'Internationalization',
link: {type: 'doc', id: 'i18n/introduction'},
items: [
{
type: 'doc',
id: 'i18n/tutorial',
label: 'Tutorial',
},
{
type: 'doc',
id: 'i18n/git',
label: 'Using Git',
},
{
type: 'doc',
id: 'i18n/crowdin',
label: 'Using Crowdin',
},
],
},
'guides/whats-next',
],
},
{
type: 'category',
label: 'Advanced Guides',
link: {type: 'doc', id: 'advanced/index'},
items: [
'advanced/architecture',
'advanced/plugins',
'advanced/routing',
'advanced/ssg',
'advanced/client',
],
},
{
type: 'category',
label: 'Upgrading',
link: {
type: 'doc',
id: 'migration/index',
},
items: [
'migration/v3',
{
type: 'category',
label: 'To Docusaurus v2',
items: [
'migration/v2/migration-overview',
'migration/v2/migration-automated',
'migration/v2/migration-manual',
'migration/v2/migration-versioned-sites',
'migration/v2/migration-translated-sites',
],
},
],
},
],
api: [
'cli',
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
export default sidebars;