Docusaurus로 매뉴얼 만들기 #2 사이드바와 검색 — 문서의 정보 구조 잡기

프레임워크 Docusaurus Documentation Static Site
3 분 소요

#1에서 Docusaurus로 첫 문서를 띄웠습니다. 글이 한두 편일 때는 구조가 문제 되지 않습니다. 문제는 문서가 수십 편으로 늘었을 때입니다. 매뉴얼은 독자가 “지금 보는 항목이 전체 어디쯤인지"를 늘 알아야 합니다. 그 역할을 하는 것이 사이드바와 검색입니다.

이번 시리즈는 Docusaurus로 매뉴얼 만들기 6편입니다.

  • #1 설치부터 첫 문서까지
  • #2 사이드바와 검색 — 문서의 정보 구조 잡기 ← 이번 글
  • #3 콘텐츠 작성 — 코드블록, Mermaid, admonition
  • #4 Cloudflare Pages로 배포하고 도메인 연결하기
  • #5 다국어와 버전 관리
  • #6 유지보수 — 검색, 접근성, 문서 문화

이번 글은 사이드바를 자동, 수동으로 구성하고, 검색을 붙이는 선택지를 정리하겠습니다.

사이드바는 sidebars.js로 정의한다 #

Docusaurus의 사이드바는 sidebars.js에서 결정됩니다. 두 가지 방식이 있습니다. 첫째는 폴더 구조를 그대로 따라가는 자동 생성입니다. 기본 템플릿이 이 방식입니다.

sidebars.js — 자동 생성 
export default {
  docsSidebar: [{ type: 'autogenerated', dirName: '.' }],
};

자동 생성에서는 각 문서의 sidebar_position이 순서를, 폴더의 _category_.json이 묶음 이름을 정합니다.

docs/guide/_category_.json 
{ "label": "가이드", "position": 2 }

직접 정의하기 #

순서와 구조를 완전히 통제하고 싶다면 사이드바를 직접 적습니다. 문서 id를 나열하고, category로 묶습니다.

sidebars.js — 직접 정의 
export default {
  docsSidebar: [
    'intro',
    {
      type: 'category',
      label: '가이드',
      items: ['guide/getting-started', 'guide/configuration'],
    },
  ],
};

상단 메뉴(navbar)는 docusaurus.config.js에서 사이드바를 가리키게 합니다.

docusaurus.config.js — navbar 
navbar: {
  items: [
    { type: 'docSidebar', sidebarId: 'docsSidebar', label: '문서' },
  ],
}

검색 — 내장이 아니다 #

여기서 Docusaurus는 앞선 도구들과 다릅니다. Hugo Hextra나 MkDocs Material이 검색을 기본 내장한 것과 달리, Docusaurus는 검색을 직접 붙여야 합니다. 선택지는 둘입니다.

  • Algolia DocSearch — Docusaurus가 공식 지원하는 호스팅 검색입니다. 오픈소스 프로젝트라면 무료로 신청할 수 있고, 색인을 Algolia가 관리합니다.
  • 로컬 검색 플러그인 — @easyops-cn/docusaurus-search-local 같은 플러그인을 쓰면 빌드 시점에 색인을 만들어 외부 서비스 없이 동작합니다. 한국어를 포함한 사내 문서라면 이쪽이 편합니다.

붙이는 구체적인 방법은 운영을 다루는 #6에서 정리하겠습니다.

마무리 #

이번 글에서는 sidebars.js로 사이드바를 자동, 수동으로 구성하고, 상단 메뉴를 연결하고, 검색의 두 선택지를 살펴봤습니다. 검색이 한 단계 더 손이 간다는 점만 빼면, 정보 구조를 잡는 흐름은 다른 도구와 같습니다.

다음 편에서는 콘텐츠 작성을 다룹니다. 코드블록과 Mermaid 다이어그램, 그리고 주의, 경고를 강조하는 admonition까지, 문서를 읽기 좋게 만드는 요소들을 정리하겠습니다.

X