Hugo로 매뉴얼 만들기 #6 유지보수 — 검색 색인, 접근성, 문서 문화

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

#5까지 오면 다국어와 버전까지 갖춘 문서가 됩니다. 이제 만드는 단계는 끝났습니다. 문서는 한 번 만들고 끝나는 것이 아니라, 제품과 함께 계속 자라는 것입니다. 마지막 편에서는 그 문서를 오래 살아 있게 하는 운영을 다룹니다.

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

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

이번 글은 규모를 견디는 검색, 모두를 위한 접근성, 문서를 살리는 문화 세 가지를 정리하겠습니다.

규모를 견디는 검색 — Pagefind #

#2에서 Hextra 내장 검색을 붙였습니다. 문서가 수백 편으로 늘면, 빌드 시점에 만든 색인을 한 번에 내려받는 방식은 첫 로딩을 무겁게 합니다. 이때 갈아탈 수 있는 도구가 Pagefind입니다.

Pagefind는 Hugo가 만든 public 결과물을 빌드 이후에 훑어 검색 색인을 만듭니다. 색인을 잘게 쪼개 두고 브라우저가 검색어에 필요한 조각만 그때그때 받아 가므로, 문서가 수천 편이어도 첫 로딩이 가볍습니다. 한국어 같은 언어의 분절도 무난합니다. 빌드 명령 뒤에 한 줄을 붙이면 됩니다.

Pagefind로 검색 색인 만들기 
hugo --gc --minify
npx -y pagefind --site public

검색 상자는 Pagefind가 제공하는 UI를 검색 페이지에 끼워 넣습니다.

검색 UI 붙이기 
<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js"></script>
<div id="search"></div>
<script>
  window.addEventListener('DOMContentLoaded', function () {
    new PagefindUI({ element: '#search' });
  });
</script>

모두를 위한 접근성 #

문서는 가능한 한 많은 사람이 읽을 수 있어야 합니다. Hextra는 기본 접근성이 양호하지만, 글을 쓰고 꾸미는 과정에서 깨지기 쉬운 지점이 몇 군데 있습니다.

  • 제목 위계를 건너뛰지 않습니다. 한 단계씩 내려가야 화면 낭독기가 구조를 제대로 읽습니다.
제목 위계 지키기 
# 페이지 제목 (h1, 페이지당 하나)
## 큰 절 (h2)
### 작은 절 (h3)
  • 링크 텍스트는 그 자체로 뜻이 통해야 합니다. “여기를 클릭"이 아니라 “설치 가이드"처럼 목적지를 적습니다.
  • 이미지에는 대체 텍스트를 답니다. 다이어그램을 Mermaid로 그리면 텍스트라 이 문제에서 자유롭습니다.
  • 색 대비를 지킵니다. 테마 색을 손볼 때 본문과 배경의 대비가 WCAG AA 기준(4.5:1)을 넘는지 확인합니다.

문서를 살리는 문화 #

좋은 문서 도구를 갖춰도, 갱신이 멈추면 문서는 금세 거짓말이 됩니다. 오래 살아 있는 문서의 공통점은 도구가 아니라 습관입니다.

핵심은 #1에서 시작점으로 삼았던 Docs as Code를 끝까지 지키는 것입니다. 문서를 코드와 같은 저장소에 두고, 기능을 바꾸는 Pull Request 안에서 관련 문서도 함께 고칩니다. “문서 갱신"을 작업 완료 조건에 넣으면, 코드와 문서가 따로 노는 일이 줄어듭니다.

여기에 몇 가지를 더합니다. 글마다 소유자와 최종 수정일을 드러내 오래된 글을 찾기 쉽게 하고, 깨진 링크는 빌드 단계에서 자동으로 점검하며, 큰 개편을 미루기보다 작게 자주 고칩니다. 완벽한 한 번의 정비보다, 꾸준한 작은 갱신이 문서를 살립니다.

시리즈를 닫으며 #

여섯 편에 걸쳐 Hugo와 Hextra로 문서 사이트를 처음부터 운영까지 만들었습니다. 설치하고(#1), 사이드바와 검색으로 구조를 잡고(#2), 코드블록과 다이어그램으로 내용을 채우고(#3), Cloudflare Pages로 배포하고(#4), 다국어와 버전을 더하고(#5), 끝으로 오래 유지하는 법(#6)까지 왔습니다.

블로그가 시간순 글 모음이라면, 문서 사이트는 구조화된 레퍼런스입니다. 그 차이가 도구 선택부터 운영 습관까지 전부를 갈랐습니다. 이제 여러분의 팀 문서를 이 방식으로 시작해 보시길 바랍니다.

X