侧边栏
创建侧边栏可以：
- Group multiple related documents into an ordered tree
- Display a common sidebar on each of those documents
- Provide paginated navigation, with next/previous button
要在你的 Docusaurus 网站上使用侧边栏，只需两步：
- Define a sidebars file that exports a dictionary of sidebar objects.
- Pass its path to the
@docusaurus/plugin-docsplugin directly or via@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 can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.
📄️ 使用多个侧边栏
你可以为每组想要分类到一起的 Markdown 文件创建一个侧边栏。
Default sidebar
If the sidebarPath is unspecified, Docusaurus automatically generates a sidebar for you, by using the filesystem structure of the docs folder:
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
},
],
};
你也可以显式定义你的侧边栏。
Sidebar object
侧边栏简单来说就是由一些类别、文档链接、其他超链接组成的层级结构。
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',
},
],
};
This is a sidebars file that exports one sidebar, called mySidebar. 它有三个顶层项目：两个类别和一个外部链接。 每个类别内部都有几个文档链接。
A sidebars file can contain multiple sidebar objects, identified by their object keys.
type SidebarsFile = {
[sidebarID: string]: Sidebar;
};
Theme configuration
Hideable sidebar
By enabling the themeConfig.docs.sidebar.hideable option, you can make the entire sidebar hideable, allowing users to better focus on the content. 这对于中等屏幕大小（如平板）的读者来说格外有用。
export default {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};
Auto-collapse sidebar categories
The themeConfig.docs.sidebar.autoCollapseCategories option would collapse all sibling categories when expanding one category. 这能让用户免于打开过多的菜单，帮助他们关注选定的部分。
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',
};
Passing custom props
To pass in custom props to a sidebar item, add the optional customProps object to any of the items. 这对于通过混合 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.
Sidebar Breadcrumbs
面包屑导航默认会在页面顶端渲染。它用的是当前页面的「侧边栏路径」。
这个行为可以用插件选项禁用：
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};
Complex sidebars example
来自 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;