자동 생성

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

type SidebarItemAutogenerated = {
  type: 'autogenerated';
  dirName: string; // (관련된 문서)에서 사이드바 슬라이스를 만들 소스 디렉터리
};

도큐사우루스는 docs 디렉터리에서 사이드바를 만들 수도 있습니다.

sidebars.js

module.exports = {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' 는 현재 docs 디렉터리를 의미합니다
    },
  ],
};

자동 생성 항목은 도큐사우루스에 의해 사이드바 슬라이스(카테고리 단축 표기법에서 언급한)으로 변환됩니다. 문서 또는 카테고리 유형의 항목 목록으로 다중 자동 생성 항목을 여러 디렉터리에서 가져와 하나의 사이드바 수준에서 일반 사이드바 항목과 같이 연결할 수 있습니다.

실제 예시

파일 구조가 다음과 같다고 합시다.

docs
├── api
│   ├── product1-api
│   │   └── api.md
│   └── product2-api
│       ├── basic-api.md
│       └── pro-api.md
├── intro.md
└── tutorials
    ├── advanced
    │   ├── advanced1.md
    │   ├── advanced2.md
    │   └── read-more
    │       ├── resource1.md
    │       └── resource2.md
    ├── easy
    │   ├── easy1.md
    │   └── easy2.md
    ├── tutorial-end.md
    ├── tutorial-intro.md
    └── tutorial-medium.md

그리고 모든 문서의 ID가 파일명이라고 가정합니다. 다음과 같이 자동 생성된 사이드바를 정의한다면

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: 'api', // docs/api 디렉터리에서 사이드바 슬라이스를 만듭니다.
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

다음과 같이 처리됩니다.

sidebars.js

module.exports = {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
      items: [
        'tutorial-intro',
        // docs/tutorials/easy 경로에 2개 파일
        'easy1',
        'easy2',
        'tutorial-medium',
        // docs/tutorials/hard 경로에 2개 파일과 폴더
        'advanced1',
        'advanced2',
        {
          type: 'category',
          label: 'read-more',
          items: ['resource1', 'resource2'],
        },
        'tutorial-end',
      ],
    },
    // docs/api 경로에 2개 폴더
    {
      type: 'category',
      label: 'product1-api',
      items: ['api'],
    },
    {
      type: 'category',
      label: 'product2-api',
      items: ['basic-api', 'pro-api'],
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

자동 생성 소스 디렉터리 자체가 카테고리가 되지 않은 방법에 유의하세요. 포함한 항목만 카테고리가 됩니다. 이것이 "사이드바 슬라이스"가 의미하는 바입니다.

카테고리 색인 규칙

도큐사우루스는 카테고리를 색인 문서에 자동으로 연결할 수 있습니다.

카테고리 색인 문서는 다음 파일 이름 규칙 중 하나를 따르는 문서입니다.

• index로 명명 (대소문자 구분): docs/Guides/index.md
• README로 명명 (대소문자 구분): docs/Guides/README.mdx
• 부모 폴더와 같은 이름으로 명명: docs/Guides/Guides.md

문서 링크에서 카테고리를 사용하는 방법과 같습니다.:

sidebars.js

module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {type: 'doc', id: 'Guides/index'},
      items: [],
    },
  ],
};

팁

소개 문서를 README.md로 설정하면 GitHub 인터페이스를 사용해 폴더 탐색 시 해당 문서가 표시되고 index.md로 설정하면 HTML 파일이 제공되는 형식과 유사하게 동작합니다.

팁

폴더에 인덱스 페이지가 하나만 있는 경우 카테고리가 아닌 링크로 전환됩니다. This is useful for 애셋 집합 사용 시 유용합니다.

some-doc
├── index.md
├── img1.png
└── img2.png

카테고리 인덱스 일치 사용자 정의

카테고리 인덱스 규칙을 선택 해제하거나 더 많은 규칙을 정의할 수 있습니다. sidebarItemsGenerator 콜백을 통해 여러분이 만든 isCategoryIndex 매처를 삽입할 수 있습니다. 예를 들어 자동으로 카테고리 인덱스가 될 수 있는 다른 파일명으로 intro를 선택할 수 있습니다.

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          ...args,
          isCategoryIndex: defaultCategoryIndexMatcher, // 아래에 주어진 기본 매처 구현
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex(doc) {
              return (
                // 기본 항목 외에 intro.md를 선택하세요.
                doc.fileName.toLowerCase() === 'intro' ||
                defaultCategoryIndexMatcher(doc)
              );
            },
          });
        },
      },
    ],
  ],
};매처

또는 카테고리 인덱스 규칙을 사용하지 않도록 선택합니다.

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          ...args,
          isCategoryIndex: defaultCategoryIndexMatcher, // 아래에 주어진 기본 매처 구현
          defaultSidebarItemsGenerator,
        }) {
          return defaultSidebarItemsGenerator({
            ...args,
            isCategoryIndex() {
              // 문서가 카테고리 인덱스로 자동 선택되지 않습니다.
              return false;
            },
          });
        },
      },
    ],
  ],
};

isCategoryIndex 매처는 3개의 필드를 제공합니다.

• fileName, 확장자가 없고 대소문자가 유지된 파일명
• directories, 문서 루트 디렉토리를 기준으로 _가장 낮은 수준에서 높은 수준까지_의 디렉토리 이름 목록
• extension, 선행점을 포함한 파일 확장자

예를 들어 guides/sidebar/autogenerated.md에 있는 문서 파일의 경우 매처가 받는 속성은 다음과 같습니다.

const props = {
  fileName: 'autogenerated',
  directories: ['sidebar', 'guides'],
  extension: '.md',
};

기본 구현은 다음과 같습니다.

function isCategoryIndex({fileName, directories}) {
  const eligibleDocIndexNames = [
    'index',
    'readme',
    directories[0].toLowerCase(),
  ];
  return eligibleDocIndexNames.includes(fileName.toLowerCase());
}

자동 생성된 사이드바 메타데이터

직접 작성한 사이드바 정의의 경우 sidebars.js를 통해 사이브바 항목에 메타데이터를 설정합니다. 자동 생성의 경우 도큐사우루스는 항목에 해당하는 파일에서 읽어옵니다. 또한 기본적으로 사이드바 슬라이스 내 항목은 알파벳 순서(파일, 폴더 이름을 사용)로 정렬되기 때문에 각 항목의 상대적 위치를 조정하고 싶을 수 있습니다.

문서 아이템 메타데이터

label, className, customProps 속성은 각각 프런트매터의 sidebar_label, sidebar_class_name, sidebar_custom_props에 선언되어 있습니다. Position 설정 역시 같은 방식으로 sidebar_position 프런트매터에서 설정할 수 있습니다.

docs/tutorials/tutorial-easy.md

---
sidebar_position: 2
sidebar_label: Easy
sidebar_class_name: green
---

# Easy Tutorial

This is the easy tutorial!

카테고리 아이템 메타데이터

해당 폴더에 _category_.json 또는 _category_.yml 파일을 추가합니다. 카테고리 메타데이터와 position 메타데이터도 설정할 수 있습니다. label, className, position, customProps는 기본적으로 카테고리에 연결된 문서에 해당하는 값이 있다면 해당 값을 사용합니다.

JSON

docs/tutorials/_category_.json

{
  "position": 2.5,
  "label": "Tutorial",
  "collapsible": true,
  "collapsed": false,
  "className": "red",
  "link": {
    "type": "generated-index",
    "title": "Tutorial overview"
  },
  "customProps": {
    "description": "This description can be used in the swizzled DocCard"
  }
}

YAML

docs/tutorials/_category_.yml

position: 2.5 # 부동 위치 지원
label: 'Tutorial'
collapsible: true # 카테고리 접기 허용
collapsed: false # 기본적으로 카테고리를 펼친 상태
className: red
link:
  type: generated-index
  title: Tutorial overview
customProps:
  description: This description can be used in the swizzled DocCard

정보

link가 명시적으로 지정된 경우 도큐사우루스는 기본 규칙을 적용하지 않습니다.

문서 링크는 상대적으로 지정할 수 있습니다. 카테고리가 guides 디렉토리에 생성된 경우 "link": {"type": "doc", "id": "intro"}는 guides/intro로 처리되고 기존 ID가 존재하지 않는 경우에만 intro으로 대체됩니다.

link: null을 사용해 기본 규칙을 배제하고 카테고리 인덱스 페이지를 생성하지 않을 수 있습니다.

정보

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 경로에서 숫자 접두사는 삭제합니다.

warning

메타데이터 추가 방식을 권장합니다.

숫자 접두사는 수정 시 기존 마크다운 링크도 모두 수정해주어야 해서 번거로운 작업이 생길 수 있습니다.

docs/02-Tutorial Easy/01-First Part.md

- Check the [Tutorial End](../04-End.mdx);
+ Check the [Tutorial End](../05-End.mdx);

사용자 지정 사이드바 아이템 생성기 사용하기

문서 플러그인(또는 프리셋) 설정 시 사용자 지정 sidebarItemsGenerator 함수를 설정할 수 있습니다.

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        async sidebarItemsGenerator({
          defaultSidebarItemsGenerator,
          numberPrefixParser,
          item,
          version,
          docs,
          categoriesMetadata,
          isCategoryIndex,
        }) {
          // 예시: 정적 사이드바 아이템의 하드코딩된 목록을 반환
          return [
            {type: 'doc', id: 'doc1'},
            {type: 'doc', id: 'doc2'},
          ];
        },
      },
    ],
  ],
};

팁

제너레이터를 처음부터 만드는 대신 기본 제너레이터를 재사용하고 향상시킵니다. 제공하는 기본 제너레이터는 길이가 250줄입니다.

사용 환경에 따라 사이드바 아이템을 추가, 변경, 필터링, 재정렬합니다.

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',
      {
        async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
          const sidebarItems = await defaultSidebarItemsGenerator(args);
          return reverseSidebarItems(sidebarItems);
        },
      },
    ],
  ],
};