사이드바

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

• Group multiple related documents into an ordered tree
• Display a common sidebar on each of those documents
• 다음/이전 버튼과 함께 페이지 탐색 기능을 지원하고 싶을 때

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

1. Define a sidebars file that exports a dictionary of sidebar objects.
2. Pass its path to the @docusaurus/plugin-docs plugin directly or via @docusaurus/preset-classic.

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: './sidebars.js',
        },
      },
    ],
  ],
};

Node.js runtime

The sidebars file is run with Node.js. You can't use or import browsers APIs, React or JSX in it.

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

📄️ 사이드바 아이템

The sidebar supports various item types:

📄️ 자동 생성

도큐사우루스는 여러분의 파일시스템 구조에 따라 자동으로 사이드바를 만듭니다. 각 디렉터리가 사이드바 카테고리로, 각 파일이 문서 링크로 만들어집니다.

📄️ 여러 개의 사이드바 사용하기

그룹으로 묶을 각 마크다운 파일 집합을 사이드바로 만들 수 있습니다.

기본 사이드바

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

sidebars.js

export default {
  mySidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // generate sidebar from the docs folder (or versioned_docs/<version>)
    },
  ],
};

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

Sidebar 오브젝트

A sidebar is a hierarchy of categories, doc links, and other hyperlinks.

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

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

sidebars.js

export default {
  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

export default {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: true,
      },
    },
  },
};

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

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

docusaurus.config.js

export default {
  themeConfig: {
    docs: {
      sidebar: {
        autoCollapseCategories: true,
      },
    },
  },
};

Passing CSS classes

To pass CSS classes to a sidebar item, add the optional className attribute to any of the items. This is useful to apply visual customizations to specific sidebar items.

{
  type: 'doc',
  id: 'doc1',
  className: 'sidebar-item--highlighted',
};

사용자 지정 속성 설정하기

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

Passing a unique key

Passing a unique key attribute can help uniquely identify a sidebar item. Sometimes other attributes (such as label) are not enough to distinguish two sidebar items from each other.

{
  type: 'category',
  label: 'API', // You may have multiple categories with this widespread label
  key: 'api-for-feature-1', // and now, they can be uniquely identified
};

How is this useful?

Docusaurus only uses the key attribute to generate unique i18n translation keys. When a translation key conflict happens (issue), Docusaurus will tell you to apply a key to distinguish sidebar items.

Alternatively, you may have your own reasons for using the key attribute that will be passed to the respective sidebar item React components.

사이드바 이동 경로

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

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

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          breadcrumbs: false,
        },
      },
    ],
  ],
};

복잡한 사이드바 예

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

sidebars.js

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;