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

사이드바

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

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

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

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

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

You can create a sidebar for each set of Markdown files that you want to group together.

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: Easysidebar_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

좀 더 쉽게 적용할 수 있도록 도큐사우루스는 다중 숫자 접두사 패턴을 지원합니다.

By default, Docusaurus will remove the number prefix from the doc id, title, label and URL paths.

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: {    hideableSidebar: true,  },};

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

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

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

복잡한 사이드바 예#

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

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