- Objective:
- Breadcrumb:
# 概念阐释
侧边栏非常有用
- 将多个相关文档分组显示在一个侧边栏中
- 为每个文档提供分页导航
- 并提供下一页/上一页按钮
## 使用侧边栏
定义一个导出边栏对象字典的文件。将此对象直接传递给@docusaurus/plugin-docs插件，或通过@docusaurus/preset-classic传递。在`config.js` 文件中
```js
presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: require.resolve('./sidebars.js'),//告诉 Docusaurus 从 `sidebars.js` 文件中加载侧边栏的配置。
// Please change this to your repo.
// Remove this to remove the "edit this page" links.
// 定义了 "编辑此页" 链接的 URL，该链接会显示在每个文档页面的底部。你应该将这个 URL 更改为你的文档源码的实际位置。
editUrl:
'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
},
```
## 侧边栏对象 Sidebar object
侧边栏的核心是一个分类、文档链接和其他超链接的层次结构。例如在`sidebars.js`文件中：
```js
//这是一个侧边栏文件，导出一个名为mySidebar的侧边栏。它有三个顶级项目：两个类别和一个外部链接。在每个类别中，有一些文档链接。
module.exports = {
mySidebar: [
{
type: 'category',//顶级项目1
label: 'Getting Started',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',//顶级项目2
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',//顶级项目3
label: 'Learn more',
href: 'https://example.com',
},
],
};
```
一个侧边栏文件可以包含[多个侧边栏对象](https://docusaurus.io/docs/sidebar/multiple-sidebars)，通过它们的对象键进行识别。
```
type SidebarsFile = {
[sidebarID: string]: Sidebar;
};
```
## 类别：创建层次结构
相关参数
```
type SidebarItemCategory = {
type: 'category'; 文件夹类别
label: string; // Sidebar label text.侧边栏显示的名字
items: SidebarItem[]; // Array of sidebar items.文件夹下的子文件
className?: string;
description?: string;
// Category options:
collapsible: boolean; // Set the category to be collapsible文件夹可折叠
collapsed: boolean; // Set the category to be initially collapsed or open by default 默认折叠，但如果想第一次打开时不折叠用false
link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};
```
添加文件夹链接
```
link: {
type: 'generated-index', //自动生成索引页
title: 'Docusaurus Guides', //html的head中的标题
description: 'Learn about the most important Docusaurus concepts!', //html的head中的描述
slug: '/category/docusaurus-guides', //显示在浏览器上的url
keywords: ['guides'], //html的head中的关键词
image: '/img/docusaurus.png', //本页的小logo
},
```
### JSON文件
在各自的文件夹中添加一个`_category_.json`或`_category_.yml`文件。您可以指定任何类别元数据以及`position`元数据。`label`、`className`、`position`和`customProps`将默认为类别链接文档的相应值（如果有）。
### 真实案例
```
docs
├── api 总文件夹1
│ ├── product1-api 子文件夹1.1
│ │ └── api.md 文件
│ └── product2-api 子文件夹1.2
│ ├── basic-api.md
│ └── pro-api.md
├── intro.md 子文件1.3
└── tutorials 总文件夹2
├── advanced 子文件夹1
│ ├── advanced1.md
│ ├── advanced2.md
│ └── read-more 孙文件夹
│ ├── resource1.md
│ └── resource2.md
├── easy 子文件夹2
│ ├── easy1.md
│ └── easy2.md
├── tutorial-end.md 子文件
├── tutorial-intro.md 子文件
└── tutorial-medium.md 子文件
```
## Using multiple sidebars
单个文件被绑定到多个Doc文件夹下
```
module.exports = {
tutorialSidebar: {
'Category A': ['doc1', 'doc2'],
},
apiSidebar: ['doc3', 'doc4'],
};
//浏览`doc1`或时`doc2`，`tutorialSidebar`会显示 ；浏览`doc3`或时`doc4`，`apiSidebar`会显示 。
```
# 实例
Docusaurus官方网站侧边栏实例,在`sidebars.js`文件夹中
```js
const sidebars = {
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: 'Migrating from v1 to v2',
items: [
'migration/migration-overview',
'migration/migration-automated',
'migration/migration-manual',
'migration/migration-versioned-sites',
'migration/migration-translated-sites',
],
},
],
api: [
'cli',
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
module.exports = sidebars;
```
# 相关内容
# 参考资料
- [Sidebar](https://docusaurus.io/docs/sidebar)