메인 컨텐츠로 이동
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',      ],    },  ],};