自动生成侧边栏
Docusaurus 可以根据你的文件系统结构自动生成侧边栏:每个文件夹会生成一个类别,每个文件会生成一个文档链接。
type SidebarItemAutogenerated = {
type: 'autogenerated';
dirName: string; // 生成侧边栏切片的源文件夹(相对文档目录)
};
Docusaurus 可以从你的 docs 文件夹中自动生成整个侧边栏:
module.exports = {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' 即当前的文档文件夹
},
],
};
Docusaurus将自动生成的
项转换为侧边栏切片(也在类别简写中讨论):一个由文档
或类别
类型的项目列表,因此您可以将来自多个目录的多个自动生成的
项与常规的侧边栏项交错地拼接到一个侧边栏级别中。
一个真实的例子
Consider this file structure:
docs
├── api
│ ├── product1-api
│ │ └── api.md
│ └── product2-api
│ ├── basic-api.md
│ └── pro-api.md
├── intro.md
└── tutorials
├── advanced
│ ├── advanced1.md
│ ├── advanced2.md
│ └── read-more
│ ├── resource1.md
│ └── resource2.md
├── easy
│ ├── easy1.md
│ └── easy2.md
├── tutorial-end.md
├── tutorial-intro.md
└── tutorial-medium.md
假设每个文档的 ID 都只是它的文件名。 如果你像这么声明了自动生成侧边栏:
module.exports = {
mySidebar: [
'intro',
{
type: 'category',
label: 'Tutorials',
items: [
'tutorial-intro',
{
type: 'autogenerated',
dirName: 'tutorials/easy', // Generate sidebar slice from docs/tutorials/easy
},
'tutorial-medium',
{
type: 'autogenerated',
dirName: 'tutorials/advanced', // Generate sidebar slice from docs/tutorials/advanced
},
'tutorial-end',
],
},
{
type: 'autogenerated',
dirName: 'api', // Generate sidebar slice from docs/api
},
{
type: 'category',
label: 'Community',
items: ['team', 'chat'],
},
],
};
It would be resolved as:
module.exports = {
mySidebar: [
'intro',
{
type: 'category',
label: 'Tutorials',
items: [
'tutorial-intro',
// Two files in docs/tutorials/easy
'easy1',
'easy2',
'tutorial-medium',
// Two files and a folder in docs/tutorials/advanced
'advanced1',
'advanced2',
{
type: 'category',
label: 'read-more',
items: ['resource1', 'resource2'],
},
'tutorial-end',
],
},
// Two folders in docs/api
{
type: 'category',
label: 'product1-api',
items: ['api'],
},
{
type: 'category',
label: 'product2-api',
items: ['basic-api', 'pro-api'],
},
{
type: 'category',
label: 'Community',
items: ['team', 'chat'],
},
],
};
Note how the autogenerate source directories themselves don't become categories: only the items they contain do. This is what we mean by "sidebar slice".
类别索引惯例
Docusaurus 可以自动给一个类别关联一篇索引文档。
类别索引文档的文件名符合下列条件之一:
- 名为
index
(大小写不敏感):docs/Guides/index.md
- 名为
README
(大小写不敏感):docs/Guides/README.mdx
- 和上一级目录的名字一致:
docs/Guides/Guides.md
这等价于一个使用了doc 链接的类别:
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'Guides/index'},
items: [],
},
],
};
把引言文档命名为 README.md
,可以在 GitHub 上浏览此目录的时候显示这篇文档;用 index.md
则会更加接近服务器发送 HTML 文件的行为。
如果一个文件夹只有一个索引页,它会变成一个链接,而不是一个类别。 这对于把资源和文档并置很有用:
some-doc
├── index.md
├── img1.png
└── img2.png
自定义类别索引匹配
你可以选择不使用三种类别索引惯例中的任何一种,或者也可以定义更多的惯例。 你可以通过 sidebarItemsGenerator
回调注入你自己的 isCategoryIndex
匹配函数。 比如,你可以选择 intro
文件名,让它也可能自动变成类别索引。
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
async sidebarItemsGenerator({
...args,
isCategoryIndex: defaultCategoryIndexMatcher, // 默认匹配函数实现,见下文
defaultSidebarItemsGenerator,
}) {
return defaultSidebarItemsGenerator({
...args,
isCategoryIndex(doc) {
return (
// 除了默认的文件名,也识别 intro.md
doc.fileName.toLowerCase() === 'intro' ||
defaultCategoryIndexMatcher(doc)
);
},
});
},
},
],
],
};
也可以选择不接受任何类别索引惯例。
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
async sidebarItemsGenerator({
...args,
isCategoryIndex: defaultCategoryIndexMatcher, // 默认匹配函数实现,见下文
defaultSidebarItemsGenerator,
}) {
return defaultSidebarItemsGenerator({
...args,
isCategoryIndex() {
// 没有文档会被自动选为类别索引
return false;
},
});
},
},
],
],
};
isCategoryIndex
匹配函数会接受一个有三个属性的对象:
fileName
,不带扩展名的文件名,区分大小写directories
,一列_从最底层到最高层_的文件夹名,相对于 文档根目录extension
,文件的扩展名,开头有一个点。
比如,对于一篇位于 guides/sidebar/autogenerated.md
的文档,匹配函数收到的参数会是:
const props = {
fileName: 'autogenerated',
directories: ['sidebar', 'guides'],
extension: '.md',
};
默认的匹配函数的实现是:
function isCategoryIndex({fileName, directories}) {
const eligibleDocIndexNames = [
'index',
'readme',
directories[0].toLowerCase(),
];
return eligibleDocIndexNames.includes(fileName.toLowerCase());
}