메인 컨텐츠로 이동
버전: Canary 🚧

사이드바

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

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

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

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

이 섹션에서는 문서 사이드바의 기타 기능에 대한 개요를 제공합니다. 다음 섹션에서는 다음 개념을 좀 더 체계적으로 소개합니다.

기본 사이드바

sidebarPath를 설정하지 않았다면 도큐사우루스에서는 docs 디렉터리의 파일 구조에 따라 사이드바를 자동 생성합니다.

sidebars.js
module.exports = {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // 문서 폴더(또는 versioned_docs/<version>)에서 사이드바 생성
},
],
};

사이드바를 명시적으로 정의할 수도 있습니다.

그 핵심에 있는 사이드바는 카테고리, 문서 링크, 기타 하이퍼링크의 계층 구조입니다.

type Sidebar =
// 일반 문법
| SidebarItem[]
// 단축 표기법 문법
| {[categoryLabel: string]: SidebarItem[]};

예를 들면 아래와 같은 형식입니다.

sidebars.js
module.exports = {
mySidebar: [
{
type: 'category',
label: 'Getting Started',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',
label: 'Learn more',
href: 'https://example.com',
},
],
};

이것은 mySidebar라는 하나의 사이드바를 내보내는 사이드바입니다. 여기에는 3개의 최상위 항목이 있습니다. 2개의 카테고리와 1개의 외부 링크로 구성됩니다. 각 카테고리 내에는 몇 가지 문서 링크가 있습니다.

사이드바 파일은 오브젝트 키로 식별되는 다중 사이드바 오브젝트를 포함할 수 있습니다.

type SidebarsFile = {
[sidebarID: string]: Sidebar;
};

테마 설정

숨길 수 있는 사이드바

themeConfig.docs.sidebar.hideable 옵션으로 설정할 수 있습니다. 전체 사이드바를 보이지 않게 해서 사용자가 콘텐츠에 집중할 수 있게 합니다. 특히 중간 크기(태블릿 같은) 스크린에서 콘텐츠를 사용할 때 유용한 기능입니다.

docusaurus.config.js
module.exports = {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};

사이드바 카테고리 자동 접기

themeConfig.docs.sidebar.autoCollapseCategories 옵션은 하나의 카테고리를 확장할 때 나머지 같은 레벨 카테고리는 축소합니다. 이렇게 하면 사용자가 너무 많은 카테고리를 열지 않고 선택한 항목에 집중할 수 있습니다.

docusaurus.config.js
module.exports = {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};

사용자 지정 속성 설정하기

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

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

기본적으로 이동 경로는 현재 페이지의 "사이드바 경로"를 사용해 맨 위에 렌더링됩니다.

이 동작은 플러그인 옵션으로 비활성화할 수 있습니다.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};

복잡한 사이드바 예

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

sidebars.js
const sidebars = {
docs: [
'introduction',
{
type: 'category',
label: 'Getting Started',
link: {
type: 'generated-index',
},
collapsed: false,
items: [
'installation',
'configuration',
'playground',
'typescript-support',
],
},
{
type: 'category',
label: 'Guides',
link: {
type: 'generated-index',
title: 'Docusaurus Guides',
description:
"Let's learn about the most important Docusaurus concepts!",
keywords: ['guides'],
image: '/img/docusaurus.png',
},
items: [
'guides/creating-pages',
{
type: 'category',
label: 'Docs',
link: {
type: 'doc',
id: 'guides/docs/introduction',
},
items: [
'guides/docs/create-doc',
{
type: 'category',
label: 'Sidebar',
link: {
type: 'doc',
id: 'guides/docs/sidebar/index',
},
items: [
'guides/docs/sidebar/items',
'guides/docs/sidebar/autogenerated',
'guides/docs/sidebar/multiple-sidebars',
],
},
'guides/docs/versioning',
'guides/docs/multi-instance',
],
},
'blog',
{
type: 'category',
label: 'Markdown Features',
link: {
type: 'doc',
id: 'guides/markdown-features/introduction',
},
items: [
'guides/markdown-features/react',
'guides/markdown-features/tabs',
'guides/markdown-features/code-blocks',
'guides/markdown-features/admonitions',
'guides/markdown-features/toc',
'guides/markdown-features/assets',
'guides/markdown-features/links',
'guides/markdown-features/plugins',
'guides/markdown-features/math-equations',
'guides/markdown-features/diagrams',
'guides/markdown-features/head-metadata',
],
},
'styling-layout',
'swizzling',
'static-assets',
'search',
'browser-support',
'seo',
'using-plugins',
'deployment',
{
type: 'category',
label: 'Internationalization',
link: {type: 'doc', id: 'i18n/introduction'},
items: [
{
type: 'doc',
id: 'i18n/tutorial',
label: 'Tutorial',
},
{
type: 'doc',
id: 'i18n/git',
label: 'Using Git',
},
{
type: 'doc',
id: 'i18n/crowdin',
label: 'Using Crowdin',
},
],
},
'guides/whats-next',
],
},
{
type: 'category',
label: 'Advanced Guides',
link: {type: 'doc', id: 'advanced/index'},
items: [
'advanced/architecture',
'advanced/plugins',
'advanced/routing',
'advanced/ssg',
'advanced/client',
],
},
{
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',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
module.exports = sidebars;