MkDocs로 매뉴얼 만들기 #5 다국어와 버전 관리

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

#4에서 문서를 인터넷에 올렸습니다. 사용자가 늘면 두 가지 요구가 따라옵니다. 하나는 다른 언어로도 보고 싶다는 것이고, 다른 하나는 옛 버전 제품을 쓰는 사람을 위해 지난 문서도 남겨 달라는 것입니다. 이번 글은 그 둘을 다룹니다.

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

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

이번 글은 언어를 추가하고, 번역 파일을 연결하고, 버전별 문서를 함께 유지하는 데까지 다루겠습니다.

언어 추가하기 — static-i18n #

다국어는 mkdocs-static-i18n 플러그인으로 붙입니다. 먼저 설치합니다.

i18n 플러그인 설치 
pip install mkdocs-static-i18n

mkdocs.yml에 언어를 선언합니다. 파일명 뒤에 언어 코드를 붙이는 방식(suffix)을 쓰겠습니다.

mkdocs.yml — 다국어 
plugins:
  - i18n:
      docs_structure: suffix
      languages:
        - locale: ko
          default: true
          name: 한국어
        - locale: en
          name: English

번역 파일 두기 #

같은 문서의 언어별 버전은 파일명 뒤에 언어 코드를 붙여 나란히 둡니다.

번역 파일 두기 
docs/
├─ index.md       # 기본 언어(한국어)
└─ index.en.md    # 영어

플러그인이 둘을 같은 글의 번역으로 인식하고, 상단에 언어 전환 메뉴를 자동으로 띄웁니다. 번역하지 않은 글은 기본 언어로 자동 대체되므로, 한 번에 전부 번역하지 않아도 사이트가 깨지지 않습니다.

버전 관리 — mike #

여기서 MkDocs의 강점이 드러납니다. Hugo 편에서는 버전 관리 기능이 없어 폴더로 직접 나눠야 했지만, MkDocs에는 mike라는 전용 도구가 있습니다. 버전마다 문서를 스냅샷으로 박아 두고, 상단에 버전 선택 드롭다운까지 붙여 줍니다.

mike로 버전 배포 
pip install mike

# 1.0 버전을 배포하고 'latest' 별칭을 붙입니다
mike deploy --push --update-aliases 1.0 latest

# 기본으로 열릴 버전을 지정합니다
mike set-default --push latest

그리고 mkdocs.yml에 버전 제공자를 mike로 지정하면, 헤더에 버전 선택기가 나타납니다.

mkdocs.yml — 버전 선택기 
extra:
  version:
    provider: mike

제품이 2.0으로 올라가면 mike deploy 2.0 latest로 새 스냅샷을 박으면 됩니다. 1.0 문서는 그대로 남아, 옛 버전을 쓰는 사용자가 계속 찾아볼 수 있습니다.

마무리 #

이번 글에서는 static-i18n으로 언어를 추가해 번역을 연결하고, mike로 버전 스냅샷과 선택기를 붙였습니다. 다국어와 버전 관리 모두 플러그인으로 깔끔하게 해결된다는 점이 MkDocs 생태계의 장점입니다.

다음 편은 마지막입니다. 검색, 접근성, 그리고 문서를 오래 살아 있게 하는 유지보수 습관까지 운영 관점을 정리하며 시리즈를 닫겠습니다.

X