Hugo 7사이트, Docusaurus 통합

Hugo PaperMod 블로그 구축에서 시작한 블로그를 Hugo에서 Docusaurus로 마이그레이션했어요. 원래 한 도메인에서 블로그 2개와 문서 노트 5개, 모두 Hugo 사이트 7개를 따로 돌렸는데 영역마다 빌드와 설정을 챙기는 일이 점점 무거워졌어요.

Docusaurus 소개

Docusaurus는 Meta가 만든 React 기반 오픈소스 정적 사이트 생성기입니다. 코드는 facebook/docusaurus에 공개되어 있습니다. 일반 블로그보다 버전 관리, 사이드바, 문서 탐색 같은 문서 사이트 기능에 초점을 맞춥니다. docs 플러그인을 여러 인스턴스로 구성할 수 있어 한 사이트 안에서도 문서 영역별 경로와 사이드바를 독립적으로 운영합니다. 블로그 플러그인 역시 여러 개를 띄울 수 있으므로 성격이 다른 블로그를 분리하기 좋습니다. Mermaid, 로컬 검색 플러그인, 다크 모드까지 문서 사이트에 필요한 기능을 생태계 안에서 함께 구성할 수 있습니다.

후보와 선택 기준

첫 번째 후보는 Hugo를 유지하고 Hextra 단일 사이트로 합치는 방식이었습니다. 기존 도구를 그대로 쓰므로 마이그레이션 비용은 가장 적지만, 문서 중심 테마라 블로그 2개의 레이아웃을 나누어 살리기에는 아쉬웠습니다.

Docusaurus는 독립된 문서 영역 여러 개와 블로그 여러 개를 공식 플러그인의 다중 인스턴스로 구성할 수 있습니다. 문서 노트 5개와 블로그 2개라는 저의 구조에 이 방식이 정확히 맞았습니다.

Astro Starlight도 빠르고 깔끔한 문서 도구였지만 기본 구조는 단일 문서 사이트에 가깝고, 블로그에는 서드파티 플러그인이 필요했습니다. 결국 새 기술의 화려함보다 지금 가진 영역을 무리 없이 한 프로젝트에 담을 수 있는지를 기준으로 Docusaurus를 골랐습니다.

힘들었던 점

첫 번째는 자동 변환의 사각지대였습니다. 변환 작업이 커밋된 파일을 기준으로 진행되면서 커밋하지 않은 글 11개가 결과에서 빠졌고, 배포 후 운영에서 404로 드러났습니다. 전체 변환을 다시 돌리면 이미 손본 글까지 덮을 수 있어 변환 스크립트에 증분 모드를 추가하고 누락된 글만 복구했습니다.

두 번째는 구 URL 보존이었습니다. 기존 주소 1,100여 개를 새 경로로 보내는 301 map을 만들었는데, URL 인코딩된 한글 태그 주소가 긴 key가 되면서 Nginx의 map_hash_bucket_size 기본값을 넘겼습니다. 설정 자체는 정상이었지만 reload가 실패했고, bucket 크기를 늘린 뒤에야 기존 주소를 유지한 채 전환할 수 있었습니다.

통합 후 모습

홈은 일곱 영역을 안내하는 카드로 바꿨습니다. 상단 메뉴에서 블로그와 문서 노트를 오갑니다.

문서 영역은 좌측 사이드바와 우측 목차가 있는 Docusaurus 기본 문서 레이아웃을 그대로 씁니다.

이제 빌드와 배포가 하나로 줄었어요. 예전 URL의 색인이 새 주소로 안정적으로 재구축되는지는 조금 더 지켜보는 중이에요.