侧边栏
创建侧边栏可以:
- 分组多篇相关文档
- 在每篇文档旁显示侧边栏
- 提供下一篇/上一篇按钮的分页导航
要在你的 Docusaurus 网站上使用侧边栏,只需两步:
- Define a sidebars file that exports a dictionary of sidebar objects.
- Pass its path to the
@docusaurus/plugin-docs
plugin directly or via@docusaurus/preset-classic
.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};
The sidebars file is run with Node.js. You can't use or import browsers APIs, React or JSX in it.
这个章节是文档侧边栏功能的一个总览。 在接下来的章节中,我们会系统地介绍下列概念:
📄️ 侧边栏项目
在上一章节中,我们介绍了三种项目类别:doc、category、link。它们的用途还是很显然的。 我们会正式介绍它们的 API。 还有第四种类型:autogenerated,我们稍后再详细解释。
📄️ 自动生成侧边栏
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,
},
},
},
};
传递自定义属性
要将自定义属性传递给侧边栏项目,请使用 customProps
字段。 这对于通过混合 React 组件呈现侧边栏项来应用网站自定义功能非常有用。
{
type: 'doc',
id: 'doc1',
customProps: {
badges: ['new', 'green'],
featured: true,
},
};
侧边栏面包屑导航
面包屑导航默认会在页面顶端渲染。它用的是当前页面的「侧边栏路径」。
这个行为可以用插件选项禁用:
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;