사이드바
사이드바는 다음과 같은 경우 유용하게 사용할 수 있습니다.
- 여러 관련 문서를 그룹으로 묶을 때
- 문서와 함께 사이드바를 표시하고 싶을 때
- 다음/이전 버튼과 함께 페이지 탐색 기능을 지원하고 싶을 때
여러분의 도큐사우루스 사이트에서 사이드바를 사용하려면 아래와 같이 설정합니다.
- sidebar 오브젝트 디렉터리를 내보낸 파일을 정의합니다.
- 오브젝트를
@docusaurus/plugin-docs플러그인에 직접 전달하거나@docusaurus/preset-classic를 통해 전달하도록 설정합니다.
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: require.resolve('./sidebars.js'),
},
},
],
],
};
이 섹션에서는 문서 사이드바의 기타 기능에 대한 개요를 제공합니다. 다음 섹션에서는 다음 개념을 좀 더 체계적으로 소개합니다.
📄️ 사이드바 아이템
이전 섹션 예시에서 doc, category, link라는 3가지 형태의 항목 유형을 소개했으며 사용법은 매우 직관적입니다. 우리는 공식 API를 통해 지원할 겁니다. 네 번째 형태인 autogenerated도 있습니다. 이에 대해서는 나중에 자세히 설명하겠습니다.
📄️ 자동 생성
도큐사우루스는 여러분의 파일시스템 구조에 따라 자동으로 사이드바를 만듭니다. 각 디렉터리가 사이드바 카테고리로, 각 파일이 문서 링크로 만들어집니다.
📄️ 여러 개의 사이드바 사용하기
그룹으로 묶을 각 마크다운 파일 집합을 사이드바로 만들 수 있습니다.
기본 사이드바
sidebarPath를 설정하지 않았다면 도큐사우루스에서는 docs 디렉터리의 파일 구조에 따라 사이드바를 자동 생성합니다.
module.exports = {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // 문서 폴더(또는 versioned_docs/<version>)에서 사이드바 생성
},
],
};
사이드바를 명시적으로 정의할 수도 있습니다.
Sidebar 오브젝트
그 핵심에 있는 사이드바는 카테고리, 문서 링크, 기타 하이퍼링크의 계층 구조입니다.
type Sidebar =
// 일반 문법
| SidebarItem[]
// 단축 표기법 문법
| {[categoryLabel: string]: SidebarItem[]};
예를 들면 아래와 같은 형식입니다.
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 옵션으로 설정할 수 있습니다. 전체 사이드바를 보이지 않게 해서 사용자가 콘텐츠에 집중할 수 있게 합니다. 특히 중간 크기(태블릿 같은) 스크린에서 콘텐츠를 사용할 때 유용한 기능입니다.
module.exports = {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};
사이드바 카테고리 자동 접기
themeConfig.docs.sidebar.autoCollapseCategories 옵션은 하나의 카테고리를 확장할 때 나머지 같은 레벨 카테고리는 축소합니다. 이렇게 하면 사용자가 너무 많은 카테고리를 열지 않고 선택한 항목에 집중할 수 있습니다.
module.exports = {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};
사용자 지정 속성 설정하기
To pass in custom props to a sidebar item, add the optional customProps object to any of the items. This is useful to apply site customizations by swizzling React components rendering sidebar items.
{
type: 'doc',
id: 'doc1',
customProps: {
badges: ['new', 'green'],
featured: true,
},
};
사이드바 이동 경로
기본적으로 이동 경로는 현재 페이지의 "사이드바 경로"를 사용해 맨 위에 렌더링됩니다.
이 동작은 플러그인 옵션으로 비활성화할 수 있습니다.
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
breadcrumbs: false,
},
},
],
],
};
복잡한 사이드바 예
도큐사우루스 사이트에서 사용하는 실제 예입니다.
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
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: 'Upgrading',
link: {
type: 'doc',
id: 'migration/index',
},
items: [
'migration/v3',
{
type: 'category',
label: 'To Docusaurus v2',
items: [
'migration/v2/migration-overview',
'migration/v2/migration-automated',
'migration/v2/migration-manual',
'migration/v2/migration-versioned-sites',
'migration/v2/migration-translated-sites',
],
},
],
},
],
api: [
'cli',
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
export default sidebars;