사이드바
사이드바는 다음과 같은 경우 유용하게 사용할 수 있습니다.
- Group multiple related documents
- Display a sidebar on each of those documents
- Provide paginated navigation, with next/previous button
여러분의 도큐사우루스 사이트에서 사이드바를 사용하려면 아래와 같이 설정합니다.
- Define a sidebars file that exports a dictionary of sidebar objects.
- Pass its path to the
@docusaurus/plugin-docsplugin directly or via@docusaurus/preset-classic.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
sidebarPath: './sidebars.js',
},
},
],
],
};
사이드바 파일은 Node.js에서 실행됩니다. 이 파일에서는 브라우저 API, 리액트 또는 JSX를 사용하거나 가져올 수 없습니다.
이 섹션에서는 문서 사이드바의 기타 기능에 대한 개요를 제공합니다. 다음 섹션에서는 다음 개념을 좀 더 체계적으로 소개합니다.
사이드바 아이템
We have introduced three types of item types in the example in the previous section autogenerated, which we will explain in detail later.
자동 생성
Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.
여러 개의 사이드바 사용하기
You can create a sidebar for each set of Markdown files that you want to group together.
기본 사이드바
sidebarPath를 지정하지 않으면 도큐사우루스가 docs 폴더의 파일 시스템 구조를 사용해 사이드바를 자동 생성합니다:
export default {
mySidebar: [
{
type: 'autogenerated',
dirName: '.', // docs 폴더(또는 versioned_docs/<version>)에서 사이드바 생성
},
],
};
사이드바를 명시적으로 정의할 수도 있습니다.
Sidebar 오브젝트
그 핵심에 있는 사이드바는 카테고리, 문서 링크, 기타 하이퍼링크의 계층 구조입니다.
type Sidebar =
// 일반 문법
| SidebarItem[]
// 단축 표기법 문법
| {[categoryLabel: string]: SidebarItem[]};
예를 들면 아래와 같은 형식입니다.
export default {
mySidebar: [
{
type: 'category',
label: '시작하기',
items: [
{
type: 'doc',
id: 'doc1',
},
],
},
{
type: 'category',
label: 'Docusaurus',
items: [
{
type: 'doc',
id: 'doc2',
},
{
type: 'doc',
id: 'doc3',
},
],
},
{
type: 'link',
label: '자세히 알아보기',
href: 'https://example.com',
},
],
};
이 사이드바 파일은 mySidebar라는 이름의 사이드바 하나를 내보냅니다. 여기에는 3개의 최상위 항목이 있습니다. 2개의 카테고리와 1개의 외부 링크로 구성됩니다. 각 카테고리 내에는 몇 가지 문서 링크가 있습니다.
사이드바 파일에는 객체 키로 구분하는 여러 사이드바 객체를 포함할 수 있습니다.
type SidebarsFile = {
[sidebarID: string]: Sidebar;
};
테마 설정
숨길 수 있는 사이드바
themeConfig.docs.sidebar.hideable 옵션을 활성화하면 사이드바 전체를 숨길 수 있어 사용자가 콘텐츠에 더 집중할 수 있습니다. 특히 중간 크기(태블릿 같은) 스크린에서 콘텐츠를 사용할 때 유용한 기능입니다.
export default {
themeConfig: {
docs: {
sidebar: {
hideable: true,
},
},
},
};
사이드바 카테고리 자동 접기
themeConfig.docs.sidebar.autoCollapseCategories 옵션은 카테고리 하나를 펼칠 때 같은 수준의 다른 카테고리를 모두 접습니다. 이렇게 하면 사용자가 너무 많은 카테고리를 열지 않고 선택한 항목에 집중할 수 있습니다.
export default {
themeConfig: {
docs: {
sidebar: {
autoCollapseCategories: true,
},
},
},
};
사용자 지정 속성 설정하기
사이드바 항목에 사용자 정의 props를 전달하려면 해당 항목에 선택적 customProps 객체를 추가하세요. 사이드바 항목을 렌더링하는 리액트 컴포넌트를 스위즐링하여 사이트를 변경할 때 유용합니다.
{
type: 'doc',
id: 'doc1',
customProps: {
badges: ['new', 'green'],
featured: true,
},
};
사이드바 이동 경로
기본적으로 이동 경로는 현재 페이지의 "사이드바 경로"를 사용해 맨 위에 렌더링됩니다.
이 동작은 플러그인 옵션으로 비활성화할 수 있습니다.
export default {
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',
{
type: 'category',
label: 'Deployment',
link: {type: 'doc', id: 'deployment/index'},
items: [
'deployment/github-pages',
'deployment/netlify',
'deployment/vercel',
],
},
{
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'],
},
],
api: [
'cli',
'docusaurus-core',
{
type: 'autogenerated',
dirName: 'api',
},
],
};
export default sidebars;