사이드바 아이템

We have introduced three types of item types in the example in the previous section: doc, category, and link, whose usages are fairly intuitive. 우리는 공식 API를 통해 지원할 겁니다. There's also a fourth type: autogenerated, which we will explain in detail later.

• Doc: link to a doc page, associating it with the sidebar
• Link: link to any internal or external page
• Category: creates a dropdown of sidebar items
• Autogenerated: generate a sidebar slice automatically
• HTML: renders pure HTML in the item's position
• *Ref: link to a doc page, without making the item take part in navigation generation

Doc: link to a doc

Use the doc type to link to a doc page and assign that doc to a sidebar:

type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut

예:

sidebars.js

export default {
  mySidebar: [
    // Normal syntax:
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },

    // Shorthand syntax:
    'doc2', // document ID
  ],
};

If you use the doc shorthand or autogenerated sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the sidebar_label Markdown front matter within that doc, which has higher precedence over the label key in the sidebar item. Similarly, you can use sidebar_custom_props to declare custom metadata for a doc page.

노트

A doc item sets an implicit sidebar association. Don't assign the same doc to multiple sidebars: change the type to ref instead.

팁

사이드바 사용자 지정 속성은 임의의 문서 메타데이터를 클라이언트측에 전파하는 유용한 방법이므로 문서 오브젝트를 가져오는 문서 관련 후크를 사용할 때 추가적인 정보를 얻을 수 있습니다.

Link: link to any page

Use the link type to link to any page (internal or external) that is not a doc.

type SidebarItemLink = {
  type: 'link';
  label: string;
  href: string;
  className?: string;
  description?: string;
};

예:

sidebars.js

export default {
  myLinksSidebar: [
    // External link
    {
      type: 'link',
      label: 'Facebook', // The link label
      href: 'https://facebook.com', // The external URL
    },

    // Internal link
    {
      type: 'link',
      label: 'Home', // The link label
      href: '/', // The internal path
    },
  ],
};

HTML: render custom markup

Use the html type to render custom HTML within the item's <li> tag.

구분선, 섹션 제목, 광고, 이미지 등과 같은 사용자 지정 항목을 삽입하는데 유용할 수 있습니다.

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // 기본 메뉴 아이템 스타일 사용
  className?: string;
};

예:

sidebars.js

export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
      defaultStyle: true, // Use the default menu item styling
    },
  ],
};

팁

The menu item is already wrapped in an <li> tag, so if your custom item is simple, such as a title, just supply a string as the value and use the className property to style it:

sidebars.js

export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Core concepts',
      className: 'sidebar-title',
    },
  ],
};

Category: create a hierarchy

Use the category type to create a hierarchy of sidebar items.

type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  className?: string;
  description?: string;

  // Category options:
  collapsible: boolean; // Set the category to be collapsible
  collapsed: boolean; // Set the category to be initially collapsed or open by default
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

예:

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

팁

Use the shorthand syntax when you don't need customizations:

sidebars.js

export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
      },
    ],
  },
};

Category links

카테고리 링크를 사용해 카테고리를 클릭하면 다른 페이지로 이동할 수 있습니다.

팁

카테고리 링크를 사용해 문서의 카테고리를 소개합니다.

Autogenerated categories can use the _category_.yml file to declare the link.

Generated index page

해당 카테고리 아래의 콘텐츠를 표시하는 색인 페이지를 자동으로 생성할 수 있습니다. The slug allows you to customize the generated page's route, which defaults to /category/[categoryName].

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {
        type: 'generated-index',
        title: 'Docusaurus Guides',
        description: 'Learn about the most important Docusaurus concepts!',
        slug: '/category/docusaurus-guides',
        keywords: ['guides'],
        image: '/img/docusaurus.png',
      },
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

See it in action on the Docusaurus Guides page.

팁

Use generated-index links as a quick way to get an introductory document.

Doc link

카테고리는 기존 문서로 연결될 수 있습니다.

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {type: 'doc', id: 'introduction'},
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

See it in action on the i18n introduction page.

Embedding generated index in doc page

You can embed the generated cards list in a normal doc page as well with the DocCardList component. 현재 문서의 상위 카테고리의 모든 사이드바 아이템을 표시합니다.

docs/sidebar/index.md

import DocCardList from '@theme/DocCardList';

<DocCardList />

http://localhost:3000

📄️ 사이드바 아이템

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.

Collapsible categories

카테고리를 펼치거나 접을 수 있는 옵션을 지원합니다. Categories are collapsible by default, but you can disable collapsing with collapsible: false.

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      items: [
        'creating-pages',
        {
          type: 'category',
          collapsible: false,
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

To make all categories non-collapsible by default, set the sidebarCollapsible option in plugin-content-docs to false:

docusaurus.config.js

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

노트

The option in sidebars.js takes precedence over plugin configuration, so it is possible to make certain categories collapsible when sidebarCollapsible is set to false globally.

Expanded categories by default

접을 수 있는 카테고리는 기본적으로 접혀 있는 상태입니다. If you want them to be expanded on the first render, you can set collapsed to false:

sidebars.js

export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        type: 'category',
        label: 'Docs',
        collapsed: false,
        items: ['markdown-features', 'sidebar', 'versioning'],
      },
    ],
  },
};

Similar to collapsible, you can also set the global configuration options.sidebarCollapsed to false. Individual collapsed options in sidebars.js will still take precedence over this configuration.

docusaurus.config.js

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

warning

When a category has collapsed: true but collapsible: false (either through sidebars.js or through plugin configuration), the latter takes precedence and the category is still rendered as expanded.

Using shorthands

You can express typical sidebar items without much customization more concisely with shorthand syntaxes. There are two parts to this: doc shorthand and category shorthand.

Doc shorthand

An item with type doc can be simply a string representing its ID:

Longhand

sidebars.js

export default {
  sidebar: [
    {
      type: 'doc',
      id: 'myDoc',
    },
  ],
};

Shorthand

sidebars.js

export default {
  sidebar: [
    'myDoc',
  ],
};

위의 예를 다음과 같이 단순하게 표현할 수 있습니다.

sidebars.js

export default {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        'doc1',
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        'doc2',
        'doc3',
      ],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Category shorthand

카테고리 항목은 키가 라벨이고 값이 하위 항목의 배열인 오브젝트로 표현할 수 있습니다.

Longhand

sidebars.js

export default {
  sidebar: [
    {
      type: 'category',
      label: 'Getting started',
      items: ['doc1', 'doc2'],
    },
  ],
};

Shorthand

sidebars.js

export default {
  sidebar: [
    {
      'Getting started': ['doc1', 'doc2'],
    },
  ],
};

이를 사용하면 예제를 다음과 같이 단순하게 표현할 수 있습니다.

sidebars.js

export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
    },
    {
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

변환 후에 각 단축 표기 오브젝트에는 정확하게 하나의 항목이 포함됩니다. 이제 아래와 같이 더 단순한 표기법을 사용할 수도 있습니다.

sidebars.js

export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

두 개의 연속적인 카테고리 단축 표기법이 두 개의 항목을 가지는 하나의 오브젝트로 압축되는 방식에 유의하세요. This syntax generates a sidebar slice: you shouldn't see that object as one bulk item—this object is unwrapped, with each entry becoming a separate item, and they spliced together with the rest of the items (in this case, the "Learn more" link) to form the final sidebar level. Sidebar slices are also important when discussing autogenerated sidebars.

하나의 카테고리 단축 표기법으로 축소된 아이템 배열이 있는 경우에는 해당 배열을 생략할 수 있습니다.

Before

sidebars.js

export default {
  sidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: [
        {
          'Basic guides': ['doc2', 'doc3'],
          'Advanced guides': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};

After

sidebars.js

export default {
  sidebar: {
    'Getting started': ['doc1'],
    Docusaurus: {
      'Basic guides': ['doc2', 'doc3'],
      'Advanced guides': ['doc4', 'doc5'],
    },
  },
};