메인 컨텐츠로 이동
Version: 2.0.0-beta.0

사이드바

사이드바는 다음과 같은 경우 유용하게 사용할 수 있습니다.

  • 여러 관련 문서를 그룹으로 묶을 때
  • 문서와 함께 사이드바를 표시하고 싶을 때
  • 다음/이전 버튼과 함께 페이지 탐색 기능을 지원하고 싶을 때

여러분의 도큐사우루스 사이트에서 사이드바를 사용하려면 아래와 같이 설정합니다.

  1. sidebar 오브젝트를 내보낸 파일을 정의합니다.
  2. 오브젝트를 @docusaurus/plugin-docs 플러그인에 직접 전달하거나 @docusaurus/preset-classic를 통해 전달하도록 설정합니다.
docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
},
],
],
};

기본 사이드바#

기본적으로 도큐사우루스에서는 docs 디렉터리의 파일 구조에 따라 사이드바를 자동 생성합니다.

sidebars.js
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
>;

예:

sidebars.js
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)을 사용하면 사이드바를 좀 더 간결하게 표현할 수 있습니다.

sidebars.js
module.exports = {
mySidebar: {
'Getting started': ['doc1'],
Docusaurus: ['doc2', 'doc3'],
},
};

여러 개의 사이드바 사용하기#

그룹으로 묶을마크다운 파일 집합을 사이드바로 만들 수 있습니다.

tip

도큐사우루스 사이트가 여러 개의 사이드바를 사용하는 좋은 예입니다.

예:

sidebars.js
module.exports = {
tutorialSidebar: {
'Category A': ['doc1', 'doc2'],
},
apiSidebar: ['doc3', 'doc4'],
};
note

tutorialSidebarapiSidebar 항목은 사이드바 내부에서 사용하는 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

예:

sidebars.js
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;
};

예:

sidebars.js
module.exports = {
mySidebar: [
{
type: 'ref',
id: 'doc1', // 문서 id (string).
},
],
};

doc1 문서가 보여질 때 도큐사우루스에서는 mySidebar 사이드바는 표시하지 않습니다.

Link: 페이지로 연결되는 링크#

문서가 아닌 페이지(내부 또는 외부)로 연결하는 링크를 만들 때 link 타입을 설정합니다.

type SidebarItemLink = {
type: 'link';
label: string;
href: string;
};

예:

sidebars.js
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; // 기본적으로 카테고리를 접을지 펼지를 설정합니다.
};

예:

sidebars.js
module.exports = {
docs: [
{
type: 'category',
label: 'Guides',
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
tip

카테고리 옵션 설정이 필요하지 않다면 단축 구문을 사용합니다.

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};

접을 수 있는 카테고리#

콘텐츠가 많은 사이트에서는 선택적으로 카테고리를 접거나 펼 수 있는 옵션을 지원합니다. 기본적으로 카테고리는 접을 수 있는 상태로 설정됩니다. 항상 펼쳐진 상태로 유지하길 원한다면 themeConfig.sidebarCollapsible 값을 false로 설정해주세요.

docusaurus.config.js
module.exports = {
themeConfig: {
sidebarCollapsible: false,
},
};

카테고리를 펼쳐진 상태로 설정하기#

접을 수 있는 카테고리를 설정한 문서는 특정 카테고리마다 상세 설정을 할 수 있습니다. 특정 카테고리는 항상 펼쳐진 상태로 표시하고 싶다면 collapsed 값을 false로 설정해주세요.

sidebars.js
module.exports = {
docs: {
Guides: [
'creating-pages',
{
type: 'category',
label: 'Docs',
collapsed: false,
items: ['markdown-features', 'sidebar', 'versioning'],
},
],
},
};

Autogenerated: 사이드바 만들기#

도큐사우루스는 여러분의 파일시스템 구조에 따라 자동으로 사이드바를 만듭니다. 각 디렉터리가 사이드바 카테고리로 만들어집니다.

자동으로 만들어진 아이템은 도큐사우루스에서 사이드바 슬라이스로 변환합니다. 사이드바 슬라이스는 doccategory 타입을 가진 아이템 목록입니다.

type SidebarItemAutogenerated = {
type: 'autogenerated';
dirName: string; // (관련된 문서)에서 사이드바 슬라이스를 만들 소스 디렉터리
};

도큐사우루스는 docs 디렉터리에서 사이드바를 만들 수도 있습니다.

sidebars.js
module.exports = {
myAutogeneratedSidebar: [
{
type: 'autogenerated',
dirName: '.', // '.' 는 현재 docs 디렉터리를 의미합니다
},
],
};

여러 개의 자동 생성된 아이템을 사이드바에서 사용하면서 일반 사이드 아이템을 추가할 수 있습니다.

sidebars.js
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'],
},
],
};

자동 생성된 사이드바 메타데이터#

기본적으로 사이드바 슬라이스는 알파벳 순(파일과 디렉터리명을 기준으로)으로 만들어집니다.

자동으로 생성된 사이드바 문서가 맘에 들지 않는다면 문서와 카테고리 설정을 위한 메타데이터를 추가할 수 있습니다.

문서의 경우: 프런트 매터에 설정을 추가합니다.

docs/tutorials/tutorial-easy.md
+ ---
+ sidebar_label: Easy
+ sidebar_position: 2
+ ---
# Easy Tutorial
This is the easy tutorial!

카테고리의 경우: _category_.json 또는 _category_.yml 파일을 적절한 디렉터리에 추가합니다.

docs/tutorials/_category_.json
{
"label": "Tutorial",
"position": 3
}
docs/tutorials/_category_.yml
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

메타데이터 추가 방식을 권장합니다.

숫자 접두사는 수정 시 기존 마크다운 링크도 모두 수정해주어야 해서 번거로운 작업이 생길 수 있습니다.

docs/02-Tutorial Easy/01-First Part.md
- Check the [Tutorial End](../04-End.md);
+ Check the [Tutorial End](../05-End.md);

사용자 지정 사이드바 아이템 생성기 사용하기#

문서 플러그인(또는 프리셋) 설정 시 사용자 지정 sidebarItemsGenerator 함수를 설정할 수 있습니다.

docusaurus.config.js
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

생성기를 처음부터 만들기보다는 기본 생성기를 재사용하고 기능을 보완합니다.

사용 환경에 따라 사이드바 아이템을 추가, 변경, 필터링, 재정렬합니다.

docusaurus.config.js
// (중첩된 카테고리 아이템을 포함해) 사이드바 아이템 순서를 반대로 바꿉니다.
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 옵션으로 설정할 수 있습니다. 전체 사이드바를 보이지 않게 해서 사용자가 콘텐츠에 집중할 수 있게 합니다. 특히 중간 크기(태블릿 같은) 스크린에서 콘텐츠를 사용할 때 유용한 기능입니다.

docusaurus.config.js
module.exports = {
themeConfig: {
// highlight-starrt
hideableSidebar: true,
},
};

사용자 지정 속성 설정하기#

사용자 지정 속성을 사이드바 아이템으로 넘기기 위해 어떤 아이템이든 customProps 오브젝트를 추가할 수 있습니다.

{
type: 'doc',
id: 'doc1',
customProps: {
/* props */
}
}

복잡한 사이드바 예#

도큐사우루스 사이트에서 사용하는 실제 예입니다.

sidebars.js
module.exports = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
collapsed: false,
items: ['installation', 'configuration', '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',
],
},
'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',
],
},
],
};