MkDocs로 매뉴얼 만들기 #2 nav와 검색 — 문서의 정보 구조 잡기

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

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

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

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

이번 글은 nav를 직접 설계하고, Material의 내비게이션 기능을 켜고, 검색을 다듬는 데까지 다루겠습니다.

nav는 mkdocs.yml에 직접 적는다 #

여기서 MkDocs의 성격이 분명히 드러납니다. 사이드바를 폴더 구조에서 자동으로 만드는 도구도 있지만, MkDocs는 mkdocs.yml의 nav에 직접 적습니다. 손이 한 번 더 가는 대신, 순서와 라벨을 완전히 통제할 수 있습니다.

mkdocs.yml — nav 
site_name: 제품 매뉴얼
theme:
  name: material

nav:
  - 홈: index.md
  - 시작하기: getting-started.md
  - 설정: configuration.md

왼쪽 라벨이 사이드바에 보이는 이름이고, 오른쪽이 docs 아래의 파일 경로입니다. nav에 적지 않은 파일은 사이드바에 나타나지 않으므로, 초안을 숨겨 두기도 쉽습니다.

섹션으로 묶기 #

항목이 늘면 묶어야 합니다. nav를 중첩하면 그대로 사이드바의 섹션이 됩니다.

mkdocs.yml — 섹션 중첩 
nav:
  - 홈: index.md
  - 가이드:
      - 시작하기: guide/getting-started.md
      - 설정: guide/configuration.md
  - 심화:
      - 플러그인: advanced/plugins.md

가이드와 심화는 펼칠 수 있는 묶음이 되고, 그 아래 글이 들어갑니다. 파일을 어떤 폴더에 두든, 사이드바 구조는 nav가 결정합니다.

보기 방식 다듬기 — 테마 기능 #

Material은 내비게이션 동작을 theme.features로 켭니다. 문서 규모에 맞게 고르면 됩니다.

mkdocs.yml — 내비게이션 기능 
theme:
  name: material
  features:
    - navigation.sections   # 섹션을 펼친 상태로 묶어 표시
    - navigation.top        # 위로 가기 버튼
    - toc.integrate         # 우측 목차를 사이드바에 통합
    - search.suggest        # 검색어 자동 완성

navigation.tabs를 더하면 최상위 섹션이 상단 탭으로 올라가고, navigation.expand는 모든 섹션을 처음부터 펼칩니다. 문서가 얕으면 탭이, 깊으면 펼침이 잘 맞습니다.

검색 #

좋은 소식은 검색을 따로 붙일 필요가 없다는 것입니다. Material은 내장 검색을 기본으로 켜 두고, 빌드 시점에 색인을 만들어 정적 파일로 함께 배포합니다. 서버가 필요 없습니다.

한 가지 손볼 곳은 한국어입니다. 기본 분절은 공백을 기준으로 단어를 나누는데, 한국어는 조사가 붙어 검색이 덜 걸릴 수 있습니다. search 플러그인의 separator를 조정해 더 잘게 끊어 줍니다.

mkdocs.yml — 검색(한국어) 
plugins:
  - search:
      separator: '[\s\-]+'

마무리 #

이번 글에서는 nav로 사이드바를 직접 설계하고, Material의 내비게이션 기능을 켜고, 검색을 한국어에 맞게 다듬었습니다. 이제 독자는 문서가 늘어도 사이드바로 위치를 가늠하고 검색으로 곧장 찾아갈 수 있습니다.

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

X