사이드바 아이템
이전 섹션 예시에서 doc
, category
, link
라는 3가지 형태의 항목 유형을 소개했으며 사용법은 매우 직관적입니다. 우리는 공식 API를 통해 지원할 겁니다. 네 번째 형태인 autogenerated
도 있습니다. 이에 대해서는 나중에 자세히 설명하겠습니다.
- Doc: 사이드바에 배치된 문서 페이지 링크입니다.
- Link: 내부 또는 외부 페이지 링크입니다.
- Category: 사이드바 아이템의 드롭다운 구조를 만듭니다.
- Autogenerated: 사이드바 슬라이스를 자동으로 만듭니다.
- HTML: 항목 위치에서 HTML을 렌더링합니다.
- *Ref: 탐색을 위한 아이템을 따로 만들지 않고 문서 페이지에 대한 링크로만 처리
Doc: 문서로 연결되는 링크
문서 페이지 링크를 만들고 사이드바에 배치하려면 doc
타입을 설정합니다.
type SidebarItemDoc =
// 일반 구문
| {
type: 'doc';
id: string;
label: string; // 사이드바 라벨 텍스트
className?: string; // 사이드바 라벨을 위한 클래스명
customProps?: Record<string, unknown>; // 사용자 지정 속성
}
// 단축 구문
| string; // 문서 id
예:
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: 페이지로 연결되는 링크
문서 가 아닌 페이지(내부 또는 외부)로 연결하는 링크를 만들 때 link
타입을 설정합니다.
type SidebarItemLink = {
type: 'link';
label: string;
href: string;
className?: string;
description?: string;
};
예:
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: 사용자 지정 마크업 렌더링
html
타입을 사용해 항목의 <li>
태그 내에서 사용자 지정 HTML을 렌더링합니다.
구분선, 섹션 제목, 광고, 이미지 등과 같은 사용자 지정 항목을 삽입하는데 유용할 수 있습니다.
type SidebarItemHtml = {
type: 'html';
value: string;
defaultStyle?: boolean; // 기본 메뉴 아이템 스타일 사용
className?: string;
};
예:
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
속성을 사용해 스타일을 지정할 수 있습니다.
export default {
myHtmlSidebar: [
{
type: 'html',
value: 'Core concepts',
className: 'sidebar-title',
},
],
};
Category: 계층 구조를 만들 때
사이드바 아이템의 계층 구조를 만들 때 category
타입을 설정합니다.
type SidebarItemCategory = {
type: 'category';
label: string; // 사이드바 라벨 텍스트
items: SidebarItem[]; // 사이드바 아이템 배열
className?: string;
description?: string;
// 카테고리 옵션:
collapsible: boolean; // 카테고리를 접을 수 있는 기능 여부 설정
collapsed: boolean; // 카테고리가 기본적으로 접힌 상태로 표시될지 여부 설정
link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};
예:
export default {
docs: [
{
type: 'category',
label: 'Guides',
collapsible: true,
collapsed: false,
items: [
'creating-pages',
{
type: 'category',
label: 'Docs',
items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
],
};
맞춤 설정이 필요하지 않다면 단축 표기 구문을 사용하세요.
export default {
docs: {
Guides: [
'creating-pages',
{
Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
},
],
},
};
카테고리 링크
카테고리 링크를 사용해 카테고리를 클릭하면 다른 페이지로 이동할 수 있습니다.
카테고리 링크를 사용해 문서의 카테고리를 소개합니다.
자동 생성된 카테고리에서는 _category_.yml
파일을 사용해 링크를 선언할 수 있습니다.
인덱스 페이지 생성하기
해당 카테고리 아래의 콘텐츠를 표시하는 색인 페이지를 자동으로 생성할 수 있습니다. slug
를 사용하면 생성된 페이지 경로를 사용자가 지정할 수 있으며 기본값은 /category/[categoryName]
입니다.
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'],
},
],
};