사이드바
사이드바는 다음과 같은 경우 유용하게 사용할 수 있습니다.
- 여러 관련 문서를 그룹으로 묶을 때
- 문서와 함께 사이드바를 표시하고 싶을 때
- 다음/이전 버튼과 함께 페이지 탐색 기능을 지원하고 싶을 때
여러분의 도큐사우루스 사이트에서 사이드바를 사용하려면 아래와 같이 설정합니다.
- sidebar 오브젝트를 내보낸 파일을 정의합니다.
- 오브젝트를
@docusaurus/plugin-docs플러그인에 직접 전달하거나@docusaurus/preset-classic를 통해 전달하도록 설정합니다.
module.exports = { presets: [ [ '@docusaurus/preset-classic', { docs: { sidebarPath: require.resolve('./sidebars.js'), }, }, ], ],};기본 사이드바#
기본적으로 도큐사우루스에서는 docs 디렉터리의 파일 구조에 따라 사이드바를 자동 생성합니다.
module.exports = { mySidebar: [ { type: 'autogenerated', dirName: '.', // generate sidebar slice from the docs folder (or versioned_docs/<version>) }, ],};사이드바를 명시적으로 정의할 수도 있습니다.
Sidebar 오브젝트#
Sidebar 오브젝트는 사이드바 아이템으로 구성된 트리 형태입니다.
type Sidebar = // 일반 구문 | SidebarItem[]
// 단축 구문 | Record< string, // 카테고리 라벨 SidebarItem[] // 카테고리 아이템 >;사이드바 파일은 여러 개의 sidebar 오브젝트를 포함할 수 있습니다.
type SidebarsFile = Record< string, // sidebar id Sidebar>;예를 들면 아래와 같이 설정합니다.
module.exports = { mySidebar: [ { type: 'category', label: 'Getting Started', items: ['doc1'], }, { type: 'category', label: 'Docusaurus', items: ['doc2', 'doc3'], }, ],};위의 예는 다음과 같은 의미입니다.
mySidebar라는 하나의 사이드바에 5개의 사이드바 아이템을 포함하고 있습니다.Getting Started,Docusaurus는 사이드바 카테고리입니다.doc1,doc2,doc3은 사이드바 문서입니다.
tip
단축 구문(shorthand syntax)을 사용하면 사이드바를 좀 더 간결하게 표현할 수 있습니다.
module.exports = { mySidebar: { 'Getting started': ['doc1'], Docusaurus: ['doc2', 'doc3'], },};여러 개의 사이드바 사용하기#
그룹으로 묶을 각 마크다운 파일 집합을 사이드바로 만들 수 있습니다.
예를 들면 아래와 같이 설정합니다.
module.exports = { tutorialSidebar: { 'Category A': ['doc1', 'doc2'], }, apiSidebar: ['doc3', 'doc4'],};note
tutorialSidebar와 apiSidebar 항목은 사이드바 내부에서 사용하는 id이며 별로 중요한 건 아닙니다.
아래 문서를 탐색할 때
doc1또는doc2:tutorialSidebar가 화면에 표시됩니다.doc3또는doc4:apiSidebar가 화면에 표시됩니다.
페이지 탐색 기능은 같은 사이드바 내에 있는 문서를 다음, 이전 버튼 링크로 연결합니다.
사이드바 아이템 살펴보기#
SidebarItem은 사이드바 트리 구조 내에 정의된 아이템입니다.
다양한 타입의 사이드바 아이템을 정의할 수 있습니다.
- Doc: 사이드바에 배치된 문서 페이지 링크입니다.
- Ref: 사이드바에 배치되지 않는 문서 페이지 링크입니다.
- Link: 내부 또는 외부 페이지 링크입니다.
- Category: 사이드바 아이템의 계층 구조를 만듭니다.
- Autogenerated: 사이드바 슬라이스를 자동으로 만듭니다.
Doc: 문서로 연결되는 링크#
문서 페이지 링크를 만들고 사이드바에 배치하려면 doc 타입을 설정합니다.
type SidebarItemDoc = // 일반 구문 | { type: 'doc'; id: string; label: string; // 사이드바 라벨 텍스트 }
// 단축 구문 | string; // 문서 id예를 들면 아래와 같이 설정합니다.
module.exports = { mySidebar: [ // 일반 구문: { type: 'doc', id: 'doc1', // 문서 id label: 'Getting started', // 사이드바 라벨 },
// 단축 구문: 'doc2', // 문서 id ],};sidebar_label 마크다운 프런트 매터는 SidebarItemDoc에 설정한 label 키보다 높은 우선순위를 가집니다.
note
같은 문서를 여러 사이드바에 설정하지 마세요: 필요하다면 ref를 사용하세요.
Ref: 사이드바 없이 문서로 연결되는 링크#
문서 페이지 링크를 만들지만 사이드바에 배치하지 않으려면 ref 타입을 설정합니다.
type SidebarItemRef = { type: 'ref'; id: string;};예를 들면 아래와 같이 설정합니다.
module.exports = { mySidebar: [ { type: 'ref', id: 'doc1', // 문서 id (string). }, ],};doc1 문서가 보여질 때 도큐사우루스에서는 mySidebar 사이드바는 표시하지 않습니다.
Link: 페이지로 연결되는 링크#
문서가 아닌 페이지(내부 또는 외부)로 연결하는 링크를 만들 때 link 타입을 설정합니다.
type SidebarItemLink = { type: 'link'; label: string; href: string;};예를 들면 아래와 같이 설정합니다.
module.exports = { myLinksSidebar: [ // 외부 링크 { type: 'link', label: 'Facebook', // 링크 라벨 href: 'https://facebook.com', // 외부 URL },
// 내부 링크 { type: 'link', label: 'Home', // 링크 라벨 href: '/', // 내부 경로 }, ],};Category: 계층 구조를 만들 때#
사이드바 아이템의 계층 구조를 만들 때 category 타입을 설정합니다.
type SidebarItemCategory = { type: 'category'; label: string; // 사이드바 라벨 텍스트 items: SidebarItem[]; // 사이드바 아이템 배열
// 카테고리 옵션: collapsed: boolean; // 기본적으로 카테고리를 접을지 펼지를 설정합니다.};예를 들면 아래와 같이 설정합니다.
module.exports = { docs: [ { type: 'category', label: 'Guides', collapsed: false, items: [ 'creating-pages', { type: 'category', label: 'Docs', items: ['introduction', 'sidebar', 'markdown-features', 'versioning'], }, ], }, ],};tip
카테고리 옵션 설정이 필요하지 않다면 단축 구문을 사용합니다.
module.exports = { docs: { Guides: [ 'creating-pages', { Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'], }, ], },};접을 수 있는 카테고리#
콘텐츠가 많은 사이트에서는 선택적으로 카테고리를 접거나 펼 수 있는 옵션을 지원합니다. 기본적으로 카테고리는 접을 수 있는 상태로 설정됩니다. 항상 펼쳐진 상태로 유지하길 원한다면 themeConfig.sidebarCollapsible 값을 false로 설정해주세요.
module.exports = { themeConfig: { sidebarCollapsible: false, },};카테고리를 펼쳐진 상태로 설정하기#
접을 수 있는 카테고리를 설정한 문서는 특정 카테고리마다 상세 설정을 할 수 있습니다. 특정 카테고리는 항상 펼쳐진 상태로 표시하고 싶다면 collapsed 값을 false로 설정해주세요.
module.exports = { docs: { Guides: [ 'creating-pages', { type: 'category', label: 'Docs', collapsed: false, items: ['markdown-features', 'sidebar', 'versioning'], }, ], },};Autogenerated: 사이드바 만들기#
도큐사우루스는 여러분의 파일시스템 구조에 따라 자동으로 사이드바를 만듭니다. 각 디렉터리가 사이드바 카테고리로 만들어집니다.
자동으로 만들어진 아이템은 도큐사우루스에서 사이드바 슬라이스로 변환합니다. 사이드바 슬라이스는 doc와 category 타입을 가진 아이템 목록입니다.
type SidebarItemAutogenerated = { type: 'autogenerated'; dirName: string; // (관련된 문서)에서 사이드바 슬라이스를 만들 소스 디렉터리};도큐사우루스는 docs 디렉터리에서 사이드바를 만들 수도 있습니다.
module.exports = { myAutogeneratedSidebar: [ { type: 'autogenerated', dirName: '.', // '.' 는 현재 docs 디렉터리를 의미합니다 }, ],};여러 개의 자동 생성된 아이템을 사이드바에서 사용하면서 일반 사이드 아이템을 추가할 수 있습니다.
module.exports = { mySidebar: [ 'intro', { type: 'category', label: 'Tutorials', items: [ 'tutorial-intro', { type: 'autogenerated', dirName: 'tutorials/easy', // docs/tutorials/easy 디렉터리에서 사이드바 슬라이스를 만듭니다. }, 'tutorial-medium', { type: 'autogenerated', dirName: 'tutorials/advanced', // docs/tutorials/hard 디렉터리에서 사이드바 슬라이스를 만듭니다. }, 'tutorial-end', ], }, { type: 'autogenerated', dirName: 'guides', // docs/guides 디렉터리에서 사이드바 슬라이스를 만듭니다. }, { type: 'category', label: 'Community', items: ['team', 'chat'], }, ],};자동 생성된 사이드바 메타데이터#
기본적으로 사이드바 슬라이스는 알파벳 순(파일과 디렉터리명을 기준으로)으로 만들어집니다.
자동으로 생성된 사이드바 문서가 맘에 들지 않는다면 문서와 카테고리 설정을 위한 메타데이터를 추가할 수 있습니다.
문서의 경우: 프런트 매터에 설정을 추가합니다.
---sidebar_label: Easysidebar_position: 2---
# Easy Tutorial
This is the easy tutorial!카테고리의 경우: _category_.json 또는 _category_.yml 파일을 적절한 디렉터리에 추가합니다.
{ "label": "Tutorial", "position": 3}label: 'Tutorial'position: 2.5 # 실수값으로 position을 설정할 수 있습니다.collapsed: false # 기본값은 카테고리가 펼쳐진 상태를 유지합니다.info
position 메타데이터는 사이드바 슬라이스 내에서만 사용됩니다. 도큐사우루스에서 사이드바의 다른 아이템 순서를 조정하지는 않습니다.
숫자 접두사 사용하기#
자동으로 만들어지는 사이드바의 순서를 조정하는 간단한 방법은 숫자 접두사를 문서나 디렉터리에 설정하는 겁니다.
docs├── 01-Intro.md├── 02-Tutorial Easy│ ├── 01-First Part.md│ ├── 02-Second Part.md│ └── 03-End.md├── 03-Tutorial Hard│ ├── 01-First Part.md│ ├── 02-Second Part.md│ ├── 03-Third Part.md│ └── 04-End.md└── 04-End.md좀 더 쉽게 적용할 수 있도록 도큐사우루스는 다중 숫자 접두사 패턴을 지원합니다.
기본적으로 도큐사우루스는 문서 id, title, label, URL 경로에서 숫자 접두사는 삭제합니다.
caution
메타데이터 추가 방식을 권장합니다.
숫자 접두사는 수정 시 기존 마크다운 링크도 모두 수정해주어야 해서 번거로운 작업이 생길 수 있습니다.
- Check the [Tutorial End](../04-End.md);+ Check the [Tutorial End](../05-End.md);사용자 지정 사이드바 아이템 생성기 사용하기#
문서 플러그인(또는 프리셋) 설정 시 사용자 지정 sidebarItemsGenerator 함수를 설정할 수 있습니다.
module.exports = { plugins: [ [ '@docusaurus/plugin-content-docs', { sidebarItemsGenerator: async function ({ defaultSidebarItemsGenerator, numberPrefixParser, item, version, docs, }) { // 예: 직접 작성한 사이드바 아이템 목록을 반환합니다. return [ {type: 'doc', id: 'doc1'}, {type: 'doc', id: 'doc2'}, ]; }, }, ], ],};tip
생성기를 처음부터 만들기보다는 기본 생성기를 재사용하고 기능을 보완합니다.
사용 환경에 따라 사이드바 아이템을 추가, 변경, 필터링, 재정렬합니다.
// (중첩된 카테고리 아이템을 포함해) 사이드바 아이템 순서를 반대로 바꿉니다.function reverseSidebarItems(items) { // 카테고리 내 아이템 순서를 반대로 바꿉니다. const result = items.map((item) => { if (item.type === 'category') { return {...item, items: reverseSidebarItems(item.items)}; } return item; }); // 현재 레벨의 아이템 순서를 반대로 바꿉니다. result.reverse(); return result;}
module.exports = { plugins: [ [ '@docusaurus/plugin-content-docs', { sidebarItemsGenerator: async function ({ defaultSidebarItemsGenerator, ...args }) { const sidebarItems = await defaultSidebarItemsGenerator(args); return reverseSidebarItems(sidebarItems); }, }, ], ],};숨길 수 있는 사이드바#
themeConfig.hideableSidebar 옵션으로 설정할 수 있습니다. 전체 사이드바를 보이지 않게 해서 사용자가 콘텐츠에 집중할 수 있게 합니다. 특히 중간 크기(태블릿 같은) 스크린에서 콘텐츠를 사용할 때 유용한 기능입니다.
module.exports = { themeConfig: { hideableSidebar: true, },};사용자 지정 속성 설정하기#
사용자 지정 속성을 사이드바 아이템으로 넘기기 위해 어떤 아이템이든 customProps 오브젝트를 추가할 수 있습니다.
{ type: 'doc', id: 'doc1', customProps: { /* 속성 */ }}복잡한 사이드바 예#
도큐사우루스 사이트에서 사용하는 실제 예입니다.
module.exports = { docs: [ 'introduction', { type: 'category', label: 'Getting Started', collapsed: false, items: [ 'installation', 'configuration', 'playground', 'typescript-support', ], }, { type: 'category', label: 'Guides', items: [ 'guides/creating-pages', { Docs: [ 'guides/docs/introduction', 'guides/docs/create-doc', 'guides/docs/sidebar', 'guides/docs/versioning', 'guides/docs/markdown-features', 'guides/docs/multi-instance', ], }, 'blog', { type: 'category', label: 'Markdown Features', items: [ 'guides/markdown-features/introduction', 'guides/markdown-features/react', 'guides/markdown-features/tabs', 'guides/markdown-features/code-blocks', 'guides/markdown-features/admonitions', 'guides/markdown-features/headings', 'guides/markdown-features/inline-toc', 'guides/markdown-features/assets', 'guides/markdown-features/plugins', 'guides/markdown-features/math-equations', 'guides/markdown-features/head-metadatas', ], }, 'styling-layout', 'static-assets', 'search', 'browser-support', 'deployment', { type: 'category', label: 'Internationalization', items: [ { type: 'doc', id: 'i18n/introduction', label: 'Introduction', }, { type: 'doc', id: 'i18n/tutorial', label: 'Tutorial', }, { type: 'doc', id: 'i18n/git', label: 'Using Git', }, { type: 'doc', id: 'i18n/crowdin', label: 'Using Crowdin', }, ], }, ], }, { type: 'category', label: 'Advanced Guides', items: ['using-plugins', 'using-themes', 'presets'], }, { 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', 'api/docusaurus.config.js', 'lifecycle-apis', { type: 'category', label: 'Plugins', items: [ 'api/plugins/plugins-overview', 'api/plugins/plugin-content-docs', 'api/plugins/plugin-content-blog', 'api/plugins/plugin-content-pages', 'api/plugins/plugin-client-redirects', 'api/plugins/plugin-debug', 'api/plugins/plugin-google-analytics', 'api/plugins/plugin-google-gtag', 'api/plugins/plugin-ideal-image', 'api/plugins/plugin-pwa', 'api/plugins/plugin-sitemap', ], }, { type: 'category', label: 'Themes', items: [ 'api/themes/themes-overview', 'api/themes/theme-configuration', 'api/themes/theme-classic', 'api/themes/theme-bootstrap', 'api/themes/theme-live-codeblock', 'api/themes/theme-search-algolia', ], }, ],};