Docusaurus 문서 사이드바와 메뉴바를 커스텀해보자

~~지금은 블로그를 옮겼지만~~ 내 마음대로 Docusaurus를 커스텀하기 위해 수많은 삽질이 있었다. 공식 문서에서도 따로 설명이 없어서 누군가의 삽질을 막기 위해 적어본다.

Docusuarus 2.0 기준으로 작성된 글입니다.

2023년 기준 공식 문서에 없는 내용이며, 자세한 내용은 최신 버전의 공식 문서를 확인해주세요.

사이드바 카테고리 타입 페이지에 커스텀 인덱스 연결하기

카테고리 타입 페이지 예시

사이드바에서 카테고리 타입(category)이고 해당 아이템을 사이드바에서 클릭할 때 자동 생성된 인덱스 파일(generated-index)이 아닌 내가 직접 만든 인덱스 파일을 연결하고 싶을 때가 있다.

우선 카테고리 폴더와 동일한 이름의 category.md 혹은 category.mdx 파일을 만든다.

├── category
│   ├── page1.md
│   └── page2.md
└── category.md // 👈 동일한 이름의 파일을 생성

그리고 사이드바 설정 파일에서 해당 카테고리 아이템의 link 부분을 아래와 같이 바꿔준다.

const sidebars = {
  wikiSidebar: [
    {
      type: "category",
      label: "My Category",
      link: {
        type: "doc",    // 👈 문서 페이지와 연결하는 것이기 때문에 "doc" 타입으로 지정
        id: "category"  // 👈 위에서 생성한 파일의 id 이력
      },
      items: [
        {
          type: "autogenerated",    // 👈 cateogory 파일 하위의 파일 기준으로 자동 생성
          dirName: "category"
        }
      ]
    }
  ]
};

module.exports = sidebars;

사이드바 아이템의 타입

문서의 사이드바에서 제공하는 아이템의 타입은 총 6가지이다. 자세한 내용은 공식 문서를 참고해주세요!

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

메뉴바에 인덱스 파일 추가하기

메뉴바 인덱스 파일 예시

메뉴바를 클릭하면 별도로 만든 인덱스 파일로 이동하고 사이드바에는 해당 인덱스 파일이 보이고 싶지 않게 하고 싶을 때가 있다. 사이드바에는 특정 파일을 제외하는 게 없고 단순히 페이지를 만들어 링크만 넣으면 사이드바가 보이지 않는 이슈가 있다.

우선 docusaurus.config.js에서 docs.routeBasePath에 지정한 폴더(여기서는 기본값인 docs로 생각한다.) 하위에 index.md 혹은 index.mdx 파일을 생성한다.

└── docs
    ├── category
    │   ├── page1.md
    │   └── page2.md
    ├── category.md
    └── index.md  // 👈 기본 문서 폴더에 index 파일 생성

그리고 해당 파일 프론트메터에 docusaurus.config.js에서 설정한 sidebarPath에서 적용한 사이드바 객체의 키값을 확인한다.

const sidebars = {
  wikiSidebar: [  // 👈 문서에 적용된 사이드바 확인
    {
      type: "category",
      label: "🖥️ Computer Science",
      link: {
        type: "doc",
        id: "computer-science",
      },
      collapsed: true,
      items: [
        ...
      ],
    },
    ...
  ]
}

module.exports = sidebars;

해당 사이드바 이름을 displayed_sidebar에 추가해주면, 사이드바가 있는 인덱스 페이지가 생성된다.

---
displayed_sidebar: wikiSidebar
---

# 문서 인덱스 파일

...