자동 생성
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; // (관련된 문서)에서 사이드바 슬라이스를 만들 소스 디렉터리
};
도큐사우루스는 docs 디렉터리에서 사이드바를 만들 수도 있습니다.
export default {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' means the current docs folder
},
],
};
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
파일 구조가 다음과 같다고 합시다.
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가 파일명이라고 가정합니다. 다음과 같이 자동 생성된 사이드바를 정의한다면
export default {
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'],
},
],
};
다음과 같이 처리됩니다.
export default {
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'],
},
],
};
자동 생성 소스 디렉터리 자체가 카테고리가 되지 않은 방법에 유의하세요. 포함한 항목만 카테고리가 됩니다. 이것이 "사이드바 슬라이스"가 의미하는 바입니다.
Category index convention
도큐사우루스는 카테고리를 색인 문서에 자동으로 연결할 수 있습니다.
카테고리 색인 문서는 다음 파일 이름 규칙 중 하나를 따르는 문서입니다.
- 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
카테고리 인덱스 규칙을 선택 해제하거나 더 많은 규칙을 정의할 수 있습니다. You can inject your own isCategoryIndex
matcher through the sidebarItemsGenerator
callback. For example, you can also pick intro
as another file name eligible for automatically becoming the category index.
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
async sidebarItemsGenerator({
...args,
isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
defaultSidebarItemsGenerator,
}) {
return defaultSidebarItemsGenerator({
...args,
isCategoryIndex(doc) {
return (
// Also pick intro.md in addition to the default ones
doc.fileName.toLowerCase() === 'intro' ||
defaultCategoryIndexMatcher(doc)
);
},
});
},
},
],
],
};
또는 카테고리 인덱스 규칙을 사용하지 않도록 선택합니다.
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
async sidebarItemsGenerator({
...args,
isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
defaultSidebarItemsGenerator,
}) {
return defaultSidebarItemsGenerator({
...args,
isCategoryIndex() {
// No doc will be automatically picked as category index
return false;
},
});
},
},
],
],
};
The isCategoryIndex
matcher will be provided with three fields:
fileName
, the file's name without extension and with casing preserveddirectories
, the list of directory names from the lowest level to the highest level, relative to the docs root directoryextension
, the file's extension, with a leading dot.
For example, for a doc file at guides/sidebar/autogenerated.md
, the props the matcher receives are
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());
}
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: Easy
sidebar_class_name: green
---
# Easy Tutorial
This is the easy tutorial!