메인 컨텐츠로 이동
버전: 불안정 🚧

사이드바 아이템

이전 섹션 예시에서 doc, category, link라는 3가지 형태의 항목 유형을 소개했으며 사용법은 매우 직관적입니다. 우리는 공식 API를 통해 지원할 겁니다. 네 번째 형태인 autogenerated도 있습니다. 이에 대해서는 나중에 자세히 설명하겠습니다.

  • Doc: 사이드바에 배치된 문서 페이지 링크입니다.
  • Link: 내부 또는 외부 페이지 링크입니다.
  • Category: 사이드바 아이템의 드롭다운 구조를 만듭니다.
  • Autogenerated: 사이드바 슬라이스를 자동으로 만듭니다.
  • HTML: 항목 위치에서 HTML을 렌더링합니다.
  • *Ref: 탐색을 위한 아이템을 따로 만들지 않고 문서 페이지에 대한 링크로만 처리

문서 페이지 링크를 만들고 사이드바에 배치하려면 doc 타입을 설정합니다.

type SidebarItemDoc =
  // 일반 구문
  | {
      type: 'doc';
      id: string;
      label: string; // 사이드바 라벨 텍스트
      className?: string; // 사이드바 라벨을 위한 클래스명
      customProps?: Record<string, unknown>; // 사용자 지정 속성
    }

  // 단축 구문
  | string; // 문서 id

예:

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. 하지만 문서 내에서 사이드바 아이템 내에서 label 키보다 높은 우선순위를 가지는 sidebar_label 마크다운 프런트매터를 사용할 수 있습니다. 마찬가지로 sidebar_custom_props를 사용해 문서 페이지에 대한 사용자 지정 메타데이터를 선언할 수 있습니다.

참고

A doc item sets an implicit sidebar association. 같은 문서를 여러 사이드바에 설정하지 마세요: 필요하다면 ref를 사용하세요.

팁

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

문서가 아닌 페이지(내부 또는 외부)로 연결하는 링크를 만들 때 link 타입을 설정합니다.

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 타입을 사용해 항목의 <li> 태그 내에서 사용자 지정 HTML을 렌더링합니다.

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

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

메뉴 아이템은 이미 <li> 태그로 감싼 상태이기 때문에 사용자 지정 항목이 제목처럼 단순한 경우 문자열을 값으로 제공하고 className 속성을 사용해 스타일을 지정할 수 있습니다.

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

사이드바 아이템의 계층 구조를 만들 때 category 타입을 설정합니다.

type SidebarItemCategory = {
  type: 'category';
  label: string; // 사이드바 라벨 텍스트
  items: SidebarItem[]; // 사이드바 아이템 배열
  className?: string;
  description?: string;

  // 카테고리 옵션:
  collapsible: boolean; // 카테고리를 접을 수 있는 기능 여부 설정
  collapsed: boolean; // 카테고리가 기본적으로 접힌 상태로 표시될지 여부 설정
  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'],
        },
      ],
    },
  ],
};
팁

맞춤 설정이 필요하지 않다면 단축 표기 구문을 사용하세요.

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

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

팁

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

자동 생성된 카테고리에서는 _category_.yml 파일을 사용해 링크를 선언할 수 있습니다.

인덱스 페이지 생성하기​

해당 카테고리 아래의 콘텐츠를 표시하는 색인 페이지를 자동으로 생성할 수 있습니다. slug를 사용하면 생성된 페이지 경로를 사용자가 지정할 수 있으며 기본값은 /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'],
    },
  ],
};

도큐사우루스 가이드 페이지에서 실제 동작을 확인할 수 있습니다.

팁

generated-index 링크를 사용해 기능 소개 문서를 빠르게 만들 수 있습니다.

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

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

i18n 소개 페이지에서 실제 동작을 확인할 수 있습니다.

문서 페이지에 생성된 인덱스 포함하기​

생성된 카드 목록을 DocCardList 컴포넌트와 함께 일반 문서 페이지에 포함할 수 있습니다. 현재 문서의 상위 카테고리의 모든 사이드바 아이템을 표시합니다.

docs/sidebar/index.md
import DocCardList from '@theme/DocCardList';

<DocCardList />
http://localhost:3000

접을 수 있는 카테고리​

카테고리를 펼치거나 접을 수 있는 옵션을 지원합니다. 기본적으로 카테고리는 접혀있는 상태입니다. 하지만 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'],
        },
      ],
    },
  ],
};

카테고리의 기본 상태를 접혀 있지 않도록 변경하려면 plugin-content-docs 옵션 중 sidebarCollapsible 값을 false로 설정합니다.

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

sidebars.js 옵션은 플러그인 설정보다 우선 적용되므로 sidebarCollapsible 값을 false로 전역 설정하더라도 특정 카테고리는 접히도록 설정할 수 있습니다.

카테고리를 펼쳐진 상태로 설정하기​

접을 수 있는 카테고리는 기본적으로 접혀 있는 상태입니다. 처음 화면이 표시될 때 펼쳐진 상태로 표시하려면 collapsed 값을 false으로 설정하세요.

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

collapsible과 마찬가지로 전역 설정인 options.sidebarCollapsed 값을 false으로 설정할 수 있습니다. 개별 sidebars.js의 collapsed 옵션이 전역 구성보다 우선 적용됩니다.

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

카테고리 설정은 collapsed: true이지만 sidebars.js 또는 플로그인 설정에서는 collapsible: false인 경우 후자가 우선 적용되지만 특정 카테고리는 펼쳐진 상태로 처리됩니다.

단축 표기법 사용하기​

단축 표기 구문을 사용하면 별도의 사용자 정의 없이 일반적인 사이드바 항목을 좀 더 간결하게 표현할 수 있습니다. 여기에는 문서 단축 표기법과 카테고리 단축 표기법 두 가지가 있습니다.

문서 단축 표기법​

doc 유형의 항목은 간단하게 문자열 ID로 표현할 수 있습니다.

sidebars.js
export default {
  sidebar: [
    {
      type: 'doc',
      id: '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',
    },
  ],
};

카테고리 단축 표기법​

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

sidebars.js
export default {
  sidebar: [
    {
      type: 'category',
      label: 'Getting started',
      items: ['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',
    },
  ],
};

두 개의 연속적인 카테고리 단축 표기법이 두 개의 항목을 가지는 하나의 오브젝트로 압축되는 방식에 유의하세요. 해당 구문에서는 사이드바 슬라이스를 만듭니다. 해당 오브젝트를 하나의 큰 항목으로 보면 안됩니다. 오브젝트를 살펴보면 각 항목은 별도의 항목이며 나머지 항목(예제에서는 "Learn more" 링크)과 함께 연결되어 최종 사이드바 수준을 구성합니다. 사이드바 슬라이스는 자동 생성 사이드바를 논의할 때도 중요합니다.

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

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