自动生成侧边栏
Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.
type SidebarItemAutogenerated = {
type: 'autogenerated';
dirName: string; // 生成侧边栏切片的源文件夹(相对文档目录)
};
Docusaurus 可以从你的 docs 文件夹中自动生成整个侧边栏:
export default {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' 即当前 docs 文件夹
},
],
};
An autogenerated
item is converted by Docusaurus to a sidebar slice (also discussed in category shorthands): a list of items of type doc
or category
, so you can splice multiple autogenerated
items from multiple directories, interleaving them with regular sidebar items, in one sidebar level.
A real-world example
Category index convention
Docusaurus 可以自动给一个类别关联一篇索引文档。
类别索引文档的文件名符合下列条件之一:
- Named as
index
(case-insensitive):docs/Guides/index.md
- Named as
README
(case-insensitive):docs/Guides/README.mdx
- Same name as parent folder:
docs/Guides/Guides.md
This is equivalent to using a category with a doc link:
export default {
docs: [
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'Guides/index'},
items: [],
},
],
};
Naming your introductory document README.md
makes it show up when browsing the folder using the GitHub interface, while using index.md
makes the behavior more in line with how HTML files are served.
如果一个文件夹只有一个索引页,它会变成一个链接,而不是一个类别。 This is useful for asset collocation:
some-doc
├── index.md
├── img1.png
└── img2.png
Customizing category index matching
Autogenerated sidebar metadata
For handwritten sidebar definitions, you would provide metadata to sidebar items through sidebars.js
; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item because, by default, items within a sidebar slice will be generated in alphabetical order (using file and folder names).
Doc item metadata
The label
, className
, and customProps
attributes are declared in front matter as sidebar_label
, sidebar_class_name
, and sidebar_custom_props
, respectively. Position can be specified in the same way, via sidebar_position
front matter.
---
sidebar_position: 2
sidebar_label: 简单
sidebar_class_name: green
---
# 简单教程
这里是简单教程!
Category item metadata
Add a _category_.json
or _category_.yml
file in the respective folder. You can specify any category metadata and also the position
metadata. label
, className
, position
, and customProps
will default to the respective values of the category's linked doc, if there is one.
- JSON
- YAML
{
"position": 2.5,
"label": "Tutorial",
"collapsible": true,
"collapsed": false,
"className": "red",
"link": {
"type": "generated-index",
"title": "Tutorial overview"
},
"customProps": {
"description": "This description can be used in the swizzled DocCard"
}
}
position: 2.5 # float position is supported
label: 'Tutorial'
collapsible: true # make the category collapsible
collapsed: false # keep the category open by default
className: red
link:
type: generated-index
title: Tutorial overview
customProps:
description: This description can be used in the swizzled DocCard
If the link
is explicitly specified, Docusaurus will not apply any default conventions.
The doc links can be specified relatively, e.g. if the category is generated with the guides
directory, "link": {"type": "doc", "id": "intro"}
will be resolved to the ID guides/intro
, only falling back to intro
if a doc with the former ID doesn't exist.
You can also use link: null
to opt out of default conventions and not generate any category index page.
The position metadata is only used within a sidebar slice: Docusaurus does not re-order other items of your sidebar.
Using number prefixes
有一种简单的给自动生成侧边栏排序的方法,就是给每个文档和文件夹添加一个数字前缀。这会让它们在文件系统按文件名排序时也是有序的:
docs
├── 01-Intro.md
├── 02-Tutorial Easy
│ ├── 01-First Part.md
│ ├── 02-Second Part.md
│ └── 03-End.md
├── 03-Tutorial Advanced
│ ├── 01-First Part.md
│ ├── 02-Second Part.md
│ ├── 03-Third Part.md
│ └── 04-End.md
└── 04-End.md
To make it easier to adopt, Docusaurus supports multiple number prefix patterns.
By default, Docusaurus will remove the number prefix from the doc id, title, label, and URL paths.
Prefer using additional metadata.
Updating a number prefix can be annoying, as it can require updating multiple existing Markdown links:
- 查看[教程结语](../04-End.mdx);
+ 查看[教程结语](../05-End.mdx);
Customize the sidebar items generator
You can provide a custom sidebarItemsGenerator
function in the docs plugin (or preset) config:
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
async sidebarItemsGenerator({
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
categoriesMetadata,
isCategoryIndex,
}) {
// 示例:返回一列硬编码的静态侧边栏项目
return [
{type: 'doc', id: 'doc1'},
{type: 'doc', id: 'doc2'},
];
},
},
],
],
};
Re-use and enhance the default generator instead of writing a generator from scratch: the default generator we provide is 250 lines long.
Add, update, filter, re-order the sidebar items according to your use case:
// Reverse the sidebar items ordering (including nested category items)
function reverseSidebarItems(items) {
// Reverse items in categories
const result = items.map((item) => {
if (item.type === 'category') {
return {...item, items: reverseSidebarItems(item.items)};
}
return item;
});
// Reverse items at current level
result.reverse();
return result;
}
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
const sidebarItems = await defaultSidebarItemsGenerator(args);
return reverseSidebarItems(sidebarItems);
},
},
],
],
};