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

프레임워크 Hugo Documentation Static Site
4 분 소요

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

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

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

이번 글은 폴더 구조로 사이드바를 만들고, weight로 순서를 잡고, 상단 메뉴와 검색을 붙이는 데까지 다루겠습니다.

폴더가 곧 사이드바다 #

Hextra에서 사이드바는 따로 설정 파일로 적는 것이 아니라, content 아래의 폴더와 파일 구조가 그대로 사이드바 위계가 됩니다. 다음 구조를 보겠습니다.

content 구조 
content/
├─ _index.md
└─ docs/
   ├─ _index.md            # "문서" 섹션
   ├─ getting-started.md
   ├─ configuration.md
   └─ advanced/
      ├─ _index.md         # "심화" 하위 섹션
      └─ plugins.md

이 구조는 사이드바에서 문서라는 항목 아래에 getting-started, configuration이 들어가고, 그 아래 심화 항목이 다시 plugins를 품는 트리로 나타납니다. 문서를 늘리는 일이 곧 폴더를 정리하는 일이 되는 셈입니다.

섹션 만들기 — _index.md #

폴더를 사이드바의 한 묶음(섹션)으로 만드는 열쇠는 _index.md입니다. 폴더에 _index.md가 있으면 Hugo는 그 폴더를 하나의 섹션으로 다루고, 사이드바에 펼칠 수 있는 항목으로 표시합니다.

섹션 전체에 공통 설정을 적용할 때는 cascade를 씁니다. 예를 들어 docs 아래 모든 페이지에 Hextra의 문서 레이아웃을 적용하려면 다음처럼 적습니다.

content/docs/_index.md 
---
title: 문서
cascade:
  type: docs
---

cascade로 내려준 설정은 하위 모든 페이지에 적용되므로, 페이지마다 같은 값을 반복해 적을 필요가 없습니다.

순서 정하기 — weight #

사이드바의 기본 정렬은 문서 흐름과 잘 맞지 않습니다. 매뉴얼은 “설치 → 설정 → 심화"처럼 읽는 순서가 정해져 있는데, 기본값은 그 순서를 모르기 때문입니다. 순서는 각 페이지의 weight로 명시합니다. 숫자가 작을수록 위에 옵니다.

content/docs/getting-started.md 
---
title: 시작하기
weight: 1
---

configuration.md에 weight: 2, 그다음 글에 weight: 3을 주는 식으로, 읽기 순서대로 번호를 매기면 됩니다. 나중에 글 사이에 새 글을 끼워야 할 때를 대비해 10, 20, 30처럼 띄워 두면 편합니다.

사이드바 다듬기 — 펼침과 제외 #

깊은 트리는 기본적으로 접혀 있습니다. 특정 섹션을 처음부터 펼쳐 두려면 그 섹션의 _index.md에 다음을 적습니다.

기본으로 펼치기 
---
title: 문서
sidebar:
  open: true
---

아직 공개하고 싶지 않은 글은 draft: true로 두면 운영 빌드에서 빠집니다. 사이드바에는 두되 검색 결과에서만 빼고 싶다면 excludeSearch: true를 씁니다.

검색에서 제외 
---
title: 내부 메모
excludeSearch: true
---

상단 메뉴 — navbar #

사이드바가 문서 내부의 길이라면, 상단 메뉴(navbar)는 사이트 전체의 큰 갈래입니다. hugo.yaml의 menu.main에 항목을 적습니다.

hugo.yaml — 상단 메뉴 
menu:
  main:
    - name: 문서
      pageRef: /docs
      weight: 1
    - name: 검색
      weight: 2
      params:
        type: search

pageRef는 사이트 안의 경로를 가리키고, 외부 링크가 필요하면 url을 대신 씁니다. 검색 항목처럼 params.type: search를 주면 그 자리에 검색 상자가 들어갑니다.

검색 붙이기 #

Hextra는 별도 서비스 없이 동작하는 검색을 기본으로 내장합니다. FlexSearch가 빌드 시점에 문서 색인을 만들어 정적 파일로 함께 배포하므로, 서버나 외부 API가 필요 없습니다. hugo.yaml에서 켜고 끌 수 있습니다.

hugo.yaml — 검색 
params:
  search:
    enable: true
    type: flexsearch
    flexsearch:
      index: content

한 가지 짚어 둘 점은 한국어 검색입니다. FlexSearch의 기본 분절 방식은 영어 같은 띄어쓰기 언어에 맞춰져 있어, 한글은 단어 중간부터 검색하면 덜 걸릴 수 있습니다. 실제 문서에서 검색 품질이 아쉽다면 분절 옵션을 조정하거나, 규모가 큰 다국어 문서라면 Pagefind 같은 대안을 #6에서 함께 살펴보겠습니다.

마무리 #

이번 글에서는 폴더 구조로 사이드바를 만들고, weight로 순서를 잡고, 상단 메뉴와 내장 검색을 붙였습니다. 이제 독자는 문서가 늘어도 사이드바로 위치를 가늠하고 검색으로 곧장 찾아갈 수 있습니다.

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

X