자동 생성
도큐사우루스는 여러분의 파일시스템 구조에 따라 자동으로 사이드바를 만듭니다. 각 디렉터리가 사이드바 카테고리로, 각 파일이 문서 링크로 만들어집니다.
type SidebarItemAutogenerated = {
type: 'autogenerated';
dirName: string; // (관련된 문서)에서 사이드바 슬라이스를 만들 소스 디렉터리
};
도큐사우루스는 docs 디렉터리에서 사이드바를 만들 수도 있습니다.
export default {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' means the current docs folder
},
],
};
자동 생성 항목은 도큐사우루스에 의해 사이드바 슬라이스(카테고리 단축 표기법에서 언급한)으로 변환됩니다. 문서 또는 카테고리 유형의 항목 목록으로 다중 자동 생성 항목을 여러 디렉터리에서 가져와 하나의 사이드바 수준에서 일반 사이드바 항목과 같이 연결할 수 있습니다.
실제 예시
파일 구조가 다음과 같다고 합시다.
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'],
},
],
};
자동 생성 소스 디렉터리 자체가 카테고리가 되지 않은 방법에 유의하세요. 포함한 항목만 카테고리가 됩니다. 이것이 "사이드바 슬라이스"가 의미하는 바입니다.
카테고리 색인 규칙
도큐사우루스는 카테고리를 색인 문서에 자동으로 연결할 수 있습니다.
카테고리 색인 문서는 다음 파일 이름 규칙 중 하나를 따르는 문서입니다.
index로 명명 (대소문자 구분):docs/Guides/index.mdREADME로 명명 (대소문자 구분):docs/Guides/README.mdx- 부모 폴더와 같은 이름으로 명명:
docs/Guides/Guides.md
문서 링크에서 카테고리를 사용하는 방법과 같습니다.:
export default {
docs: [
{
type: 'category',
label: 'Guides',
link: {type: 'doc', id: 'Guides/index'},
items: [],
},
],
};
소개 문서를 README.md로 설정하면 GitHub 인터페이스를 사용해 폴더 탐색 시 해당 문서가 표시되고 index.md로 설정하면 HTML 파일이 제공되는 형식과 유사하게 동작합니다.
폴더에 인덱스 페이지가 하나만 있는 경우 카테고리가 아닌 링크로 전환됩니다. This is useful for 애셋 집합 사용 시 유용합니다.
some-doc
├── index.md
├── img1.png
└── img2.png
카테고리 인덱스 일치 사용자 정의
카테고리 인덱스 규칙을 선택 해제하거나 더 많은 규칙을 정의할 수 있습니다. sidebarItemsGenerator 콜백을 통해 여러분이 만든 isCategoryIndex 매처를 삽입할 수 있습니다. 예를 들어 자동으로 카테고리 인덱스가 될 수 있는 다른 파일명으로 intro를 선택할 수 있습니다.
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;
},
});
},
},
],
],
};
isCategoryIndex 매처는 3개의 필드를 제공합니다.
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());
}
자동 생성된 사이드바 메타데이터
직접 작성한 사이드바 정의의 경우 sidebars.js를 통해 사이브바 항목에 메타데이터를 설정합니다. 자동 생성의 경우 도큐사우루스는 항목에 해당하는 파일에서 읽어옵니다. 또한 기본적으로 사이드바 슬라이스 내 항목은 알파벳 순서(파일, 폴더 이름을 사용)로 정렬되기 때문에 각 항목의 상대적 위치를 조정하고 싶을 수 있습니다.
문서 아이템 메타데이터
label, className, customProps 속성은 각각 프런트매터의 sidebar_label, sidebar_class_name, sidebar_custom_props에 선언되어 있습니다. Position 설정 역시 같은 방식으로 sidebar_position 프런트매터에서 설정할 수 있습니다.
---
sidebar_position: 2
sidebar_label: Easy
sidebar_class_name: green
---
# Easy Tutorial
This is the easy tutorial!
카테고리 아이템 메타데이터
해당 폴더에 _category_.json 또는 _category_.yml 파일을 추가합니다. 카테고리 메타데이터와 position 메타데이터도 설정할 수 있습니다. label, className, position, customProps는 기본적으로 카테고리에 연결된 문서에 해당하는 값이 있다면 해당 값을 사용합니다.
- 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 # 부동 위치 지원
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
link가 명시적으로 지정된 경우 도큐사우루스는 기본 규칙을 적용하지 않습니다.
문서 링크는 상대적으로 지정할 수 있습니다. 카테고리가 guides 디렉토리에 생성된 경우 "link": {"type": "doc", "id": "intro"}는 guides/intro로 처리되고 기존 ID가 존재하지 않는 경우에만 intro으로 대체됩니다.
link: null을 사용해 기본 규칙을 배제하고 카테고리 인덱스 페이지를 생성하지 않을 수 있습니다.
position 메타데이터는 사이드바 슬라이스 내에서만 사용됩니다. 도큐사우루스에서 사이드바의 다른 아이템 순서를 조정하지는 않습니다.
숫자 접두사 사용하기
자동 생성된 사이바를 정렬하는 간단한 방법은 문서와 폴더에 번호 접수사를 붙이면 파일명 기준으로 정렬 시 같은 순서로 파일 시스템에 표시됩니다.
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
좀 더 쉽게 적용할 수 있도록 도큐사우루스는 다중 숫자 접두사 패턴을 지원합니다.
기본적으로 도큐사우루스는 문서 id, title, label, URL 경로에서 숫자 접두사는 삭제합니다.
메타데이터 추가 방식을 권장합니다.
숫자 접두사는 수정 시 기존 마크다운 링크도 모두 수정해주어야 해서 번거로운 작업이 생길 수 있습니다.
- Check the [Tutorial End](../04-End.mdx);
+ Check the [Tutorial End](../05-End.mdx);
사용자 지정 사이드바 아이템 생성기 사용하기
문서 플러그인(또는 프리셋) 설정 시 사용자 지정 sidebarItemsGenerator 함수를 설정할 수 있습니다.
export default {
plugins: [
[
'@docusaurus/plugin-content-docs',
{
async sidebarItemsGenerator({
defaultSidebarItemsGenerator,
numberPrefixParser,
item,
version,
docs,
categoriesMetadata,
isCategoryIndex,
}) {
// Example: return an hardcoded list of static sidebar items
return [
{type: 'doc', id: 'doc1'},
{type: 'doc', id: 'doc2'},
];
},
},
],
],
};
제너레이터를 처음부터 만드는 대신 기본 제너레이터를 재사용하고 향상시킵니다. 제공하는 기본 제너레이터는 길이가 250줄입니다.
사용 환경에 따라 사이드바 아이템을 추가, 변경, 필터링, 재정렬합니다.
// 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);
},
},
],
],
};