侧边栏
创建侧边栏有助于：
- 将多个 相关文档 分组
- 在每个文档上显示侧边栏
- 提供带有上一页/下一页按钮的分页导航
要在您的 Docusaurus 站点上使用侧边栏：
- 定义一个导出 侧边栏对象 字典的侧边栏文件。
- 将其路径直接传递给
@docusaurus/plugin-docs插件或通过@docusaurus/preset-classic传递。
docusaurus.config.js
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};
Node.js 运行时
侧边栏文件使用 Node.js 运行。您不能在其中使用或导入浏览器 API、React 或 JSX。
本节概述了文档侧边栏的各种功能。在以下各节中，我们将更系统地介绍以下概念：
📄️ 侧边栏项目
我们在上一节的示例中介绍了三种类型的项目：doc、category 和 link，它们的用法非常直观。我们将正式介绍它们的 API。还有一种第四种类型：autogenerated，我们将在后面详细解释。
📄️ 自动生成
Docusaurus 可以 根据您的文件系统结构自动创建侧边栏 ：每个文件夹创建一个侧边栏类别，每个文件创建一个文档链接。
📄️ 使用多个侧边栏
您可以为要 组合在一起 的每个 Markdown 文件集 创建一个侧边栏。
默认侧边栏
如果未指定 sidebarPath，Docusaurus 将 自动为您生成侧边栏 ，方法是使用 docs 文件夹的文件系统结构：
sidebars.js
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // 从 docs 文件夹（或 versioned_docs/<version>）生成侧边栏
},
],
};
您也可以显式定义您的侧边栏。
侧边栏对象
侧边栏的核心是类别、文档链接和其他超链接的层次结构。
type Sidebar =
// 常规语法
| SidebarItem[]
// 简写语法
| {[categoryLabel: string]: SidebarItem[]};
例如：
sidebars.js
export default {
mySidebar: [
{
type: 'category',
label: '入门',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',
label: '了解更多',
href: 'https://example.com',
},
],
};
这是一个导出一个名为 mySidebar 的侧边栏的侧边栏文件。它具有三个顶级项目：两个类别和一个外部链接。每个类别中都有一些文档链接。
侧边栏文件可以包含 多个侧边栏对象 ，由其对象键标识。
type SidebarsFile = {
[sidebarID: string]: Sidebar;
};
主题配置
可隐藏侧边栏
通过启用 themeConfig.docs.sidebar.hideable 选项，您可以使整个侧边栏可隐藏，从而使用户能够更好地专注于内容。这在中等大小的屏幕（例如平板电脑）上使用内容时尤其有用。
docusaurus.config.js
export default {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};
自动折叠侧边栏类别
themeConfig.docs.sidebar.autoCollapseCategories 选项会在展开一个类别时折叠所有同级类别。这可以防止用户打开过多的类别，并帮助他们专注于所选部分。
docusaurus.config.js
export default {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};
传递自定义属性
要将自定义属性传递到侧边栏项目，请将可选的 customProps 对象添加到任何项目中。这可用于通过混用渲染侧边栏项目的 React 组件来应用站点自定义。
{
type: 'doc',
id: 'doc1',
customProps: {
badges: ['new', 'green'],
featured: true,
},
};
侧边栏面包屑
默认情况下，面包屑会使用当前页面的“侧边栏路径”在顶部渲染。
可以使用插件选项禁用此行为：
docusaurus.config.js
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};
复杂侧边栏示例
来自 Docusaurus 站点的真实示例：
sidebars.js
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: [
'introduction',
{
type: 'category',
label: '入门',
link: {
type: 'generated-index',
},
collapsed: false,
items: [
'installation',
'configuration',
'playground',
'typescript-support',
],
},
{
type: 'category',
label: '指南',
link: {
type: 'generated-index',
title: 'Docusaurus 指南',
description:
'让我们学习最重要的 Docusaurus 概念！',
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: [
'guides/creating-pages',
{
type: 'category',
label: '文档',
link: {
type: 'doc',
id: 'guides/docs/introduction',
},
items: [
'guides/docs/create-doc',
{
type: 'category',
label: '侧边栏',
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 功能',
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: '国际化',
link: {type: 'doc', id: 'i18n/introduction'},
items: [
{
type: 'doc',
id: 'i18n/tutorial',
label: '教程',
},
{
type: 'doc',
id: 'i18n/git',
label: '使用 Git',
},
{
type: 'doc',
id: 'i18n/crowdin',
label: '使用 Crowdin',
},
],
},
'guides/whats-next',
],
},
{
type: 'category',
label: '高级指南',
link: {type: 'doc', id: 'advanced/index'},
items: [
'advanced/architecture',
'advanced/plugins',
'advanced/routing',
'advanced/ssg',
'advanced/client',
],
},
{
type: 'category',
label: '升级',
link: {
type: 'doc',
id: 'migration/index',
},
items: [
'migration/v3',
{
type: 'category',
label: '升级到 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;