Docusaurus 도입기

요약

SUMMARY

Deck의 문서를 README 한 장으로 버티다, 기능이 늘며 스크롤 지옥이 되자 Docusaurus로 옮겼다. 문서를 파일 하나로 늘려가는 구조를 얻고, CLI 레퍼런스는 Cobra 명령 정의에서 자동 생성해 얹고, 한/영 번역은 AI(claude -p)로 돌리되 source_hash 증분·용어집·조사 정규화로 품질을 잡았다. 배포는 GitHub Pages.

README는 시작할 땐 좋은데, 딱 거기까지다.

1. README 한 장이 감당 안 되던 순간

README는 시작점으로는 최고다. 리포 열면 바로 보이고, 설치 몇 줄에 예시 몇 개면 충분하다. 문제는 도구가 자라면서 생긴다.

• 설치, 개념(워크플로우 모델), 명령별 사용법, 트러블슈팅, FAQ가 한 파일에 쌓이면서 한 화면에서 원하는 곳을 못 찾는다.
• “새 기능 추가”를 쓸 때마다 기존 README의 어느 부분을 고쳐야 흐름이 깨지지 않는지를 고민하게 된다. 문서 구조가 없으므로 매번 즉흥적으로 진행된다.
• 코드 예시·명령 옵션이 늘면 README가 그냥 길어지기만 한다. 목차를 손으로 달아도 금방 어긋난다.

결국 설명이 점점 어려워졌다. 기능이 하나면 한 문단이면 되지만, 서로 얽힌 기능이 열 개가 되면 그것을 읽기 좋게 배치하고 새 글을 간편하게 추가할 수 있는 구조가 필요했다.

2. Docusaurus 선정

정적 사이트 생성기는 많다(MkDocs, VitePress, Hugo…). Docusaurus로 기운 이유는 이렇다.

• 마크다운을 그대로 쓴다. docs/ 아래 .md 파일을 두면 사이드바에 항목이 생긴다. 새 문서를 추가하는 작업이 “파일 하나 만들기” 수준이라 부담이 없다.
• 사이드바, 이전/다음 내비게이션, 검색, 버전 표기 같은 구조가 기본으로 제공된다. README에서 손으로 흉내 내던 목차가 별도 작업 없이 생긴다.
• i18n이 1급 기능이다. 뒤에 나올 한/영 번역을 얹을 자리가 처음부터 있다.
• React 기반이라 필요하면 컴포넌트로 확장할 수 있다. 당장은 사용하지 않더라도 확장 여지가 남아 있는 셈이다.

docs/introduction.md, docs/quick-start.md, docs/workflow-model.md처럼 개념을 파일로 쪼개고, CLI 레퍼런스는 docs/cli/ 아래로 몰았다. README는 다시 “설치하고 여기(문서 사이트)로 오라”는 짧은 안내로 돌아갔다.

3. CLI 레퍼런스는 코드에서 자동 생성해 얹기

문서에서 제일 잘 어긋나는 부분이 CLI 레퍼런스다. 명령 옵션을 코드에서 바꿔 놓고 문서를 고치지 않으면 문서와 실제 동작이 어긋난다. Deck은 명령을 Cobra로 정의하는데, Cobra에는 명령 트리를 마크다운으로 출력하는 기능이 있다. 그래서 CLI 레퍼런스 마크다운을 코드에서 생성해 docs/cli/에 넣고, 그것을 Docusaurus가 렌더링한다.

cobra 명령 정의 (Short/Long/Flags)
   │  deck __gendocs <dir>  (내부 명령)
   ▼
docs/cli/*.md  (명령별 레퍼런스, 자동 생성)
   │  docusaurus build
   ▼
문서 사이트의 CLI 레퍼런스 페이지

명령을 고치면 생성 명령을 다시 실행해 docs/cli/를 갱신하고, CI에서 생성물이 최신 상태인지(make verify-generated류)를 검사한다. 손으로 쓴 문서가 아니므로 옵션이 하나 바뀌어도 레퍼런스가 항상 코드와 일치한다. README 시절에 가장 자주 발생하던 “문서만 옛날 그대로”인 문제가 이 지점에서 사라졌다.

4. 한/영 번역을 AI로 돌리기

Docusaurus i18n은 기본 로케일(en)의 docs/와 별개로 i18n/ko/.../current/ 아래 번역본을 둔다. 문제는 이것을 사람이 계속 맞춰 관리하기가 불가능하다는 점이다. 영문 문서를 고칠 때마다 한글본을 똑같이 수정하는 작업은 금방 밀린다.

그래서 번역을 스크립트로 돌렸다. 아이디어는 두 가지다.

AI를 번역 엔진으로. 영문 .md 파일을 입력으로 받아 한글본을 생성하는 스크립트를 두었다(translate-docs.mjs). 번역 엔진은 헤드리스로 호출하는 AI CLI다(claude -p 같은 형태이며, 환경변수로 다른 엔진으로 교체할 수 있다). 번역기 API를 따로 붙이는 대신 이미 쓰고 있던 코딩 에이전트를 그대로 활용한 셈이다.

소스 해시로 증분 번역. 매번 전체를 다시 번역하면 시간이 오래 걸리고 비효율적이다. 그래서 번역본 프런트매터에 원문 해시(source_hash)를 기록해 둔다. 다음에 실행할 때 원문 해시가 그대로면 해당 문서를 건너뛰고, 바뀐 문서만 다시 번역한다.

docs/quick-start.md  ──(hash 계산)──┐
                                    ▼
        i18n/ko/.../quick-start.md 의 source_hash 와 비교
             │ 같으면 skip           │ 다르면 재번역
             ▼                       ▼
           그대로                  AI 번역 → source_hash 갱신

여기에 번역 품질을 유지하는 장치 두 개를 더했다. 하나는 용어집(TERMINOLOGY.md)이다. 코드 식별자·CLI 명령·플래그·YAML 키·에러코드는 번역하지 말고 영어 그대로 두라는 규칙과 문체(문어체 ~합니다, 번역투 금지)를 프롬프트에 함께 넣는다. 그렇게 하지 않으면 deck apply를 “덱 적용”으로 옮기는 실수가 발생한다. 다른 하나는 조사 후처리다. 영어 단어를 그대로 둘 때 뒤에 붙는 조사(은/는, 이/가)는 그 단어의 실제 발음 받침에 맞춰야 자연스럽다(“deck은/deck을”). 이 부분은 AI에 맡기면 결과가 흔들리므로, 번역 뒤에 결정론적 정규화 패스를 한 번 더 실행해 고정 표기로 강제한다.

정리하면 AI 1패스와 조사 정규화 1패스를 돌리고, 해시를 비교해 바뀐 문서만 다시 번역하는 구조다. 사람은 용어집과 예외 규칙만 관리하면 되고, 영문을 고친 뒤에는 스크립트 한 번이면 한글본이 따라온다.

5. 배포는 GitHub Pages로

문서 사이트는 GitHub Pages로 배포했다. docs/나 워크플로우가 바뀌면 Actions가 npm ci && npm run build로 정적 사이트를 만들고, 그 산출물을 Pages 아티팩트로 올려 배포한다. (배포 워크플로우 자체는 GitHub Actions 글에서 CI 전반과 함께 다룬다.) 문서를 push하면 몇 분 뒤에 사이트가 갱신되므로, 문서도 코드와 같은 파이프라인으로 관리된다.

참고

• 폐쇄망 전용 싱글 바이너리 워크플로우 도구 Deck 만들기
• Cobra로 Go CLI 만들기
• GitHub Actions 입문기
• Docusaurus
• Docusaurus — i18n