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

프레임워크 Starlight Documentation Static Site
2 분 소요

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

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

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

이번 글은 사이드바를 자동, 수동으로 구성하고, 내장 검색을 확인하는 데까지 다루겠습니다.

사이드바는 설정으로 정의한다 #

Starlight의 사이드바는 astro.config.mjs의 Starlight 통합 안에서 정합니다. 두 가지 방식이 있습니다. 첫째는 폴더를 따라 자동으로 만드는 방식입니다.

astro.config.mjs — 자동 생성 
starlight({
  title: '제품 매뉴얼',
  sidebar: [
    { label: '가이드', autogenerate: { directory: 'guides' } },
  ],
})

guides 폴더 안의 문서가 가이드 묶음으로 자동 정렬됩니다. 각 글의 순서는 프런트매터의 sidebar.order로 조정합니다.

직접 정의하기 #

순서와 구조를 완전히 통제하고 싶다면 항목을 직접 적습니다.

astro.config.mjs — 직접 정의 
sidebar: [
  { label: '시작하기', link: '/intro/' },
  {
    label: '가이드',
    items: [
      { label: '설치', link: '/guides/install/' },
      { label: '설정', link: '/guides/config/' },
    ],
  },
]

label이 사이드바에 보이는 이름이고, link가 문서 경로입니다.

검색 — 기본 내장 #

좋은 소식은 검색을 따로 붙일 필요가 없다는 것입니다. Starlight는 Pagefind를 기본으로 내장합니다. 빌드 시점에 색인을 만들어 잘게 쪼개 두고, 브라우저가 검색어에 필요한 조각만 받아 가므로 문서가 많아도 가볍습니다. 서버나 외부 서비스가 필요 없고, 한국어를 포함한 문서도 무난히 검색됩니다.

검색은 개발 서버에서는 보이지 않고, npm run build로 빌드한 결과에서 동작합니다. 색인이 빌드 산출물을 훑어 만들어지기 때문입니다.

마무리 #

이번 글에서는 사이드바를 자동, 수동으로 구성하고, 기본 내장된 Pagefind 검색을 확인했습니다. 검색을 따로 신경 쓰지 않아도 된다는 점이, 정보 구조를 잡는 일을 한결 가볍게 만듭니다.

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

X