#MkDocs
7 편의 글
MkDocs로 매뉴얼 만들기 #6 유지보수 — 검색, 접근성, 문서 문화
시리즈의 마지막 편입니다. Material 내장 검색을 다듬고, 모두가 읽을 수 있게 하는 접근성, 그리고 문서를 오래 살아 있게 하는 Docs as Code 문화까지 운영 관점을 정리하며 시리즈를 닫겠습니다.
문서 사이트 생성기 비교 — Hugo, MkDocs, Docusaurus, Starlight 중 무엇을 고를까
팀 문서를 정적 사이트로 만들기로 했다면, 다음 질문은 어떤 도구로 만들 것인가입니다. Hugo, MkDocs, Docusaurus, Starlight 네 가지를 런타임, 검색, 버전 관리, 확장성 기준으로 비교하고, 상황별로 무엇을 고르면 되는지 정리하겠습니다.
MkDocs로 매뉴얼 만들기 #5 다국어와 버전 관리
하나의 문서를 여러 언어로 제공하고, 제품 버전이 올라갈 때 옛 문서를 함께 유지하는 법을 다룹니다. mkdocs-static-i18n 플러그인으로 다국어를, mike로 버전 스냅샷과 버전 선택기를 붙이는 데까지 정리하겠습니다.
MkDocs로 매뉴얼 만들기 #4 Cloudflare Pages로 배포하고 도메인 연결하기
로컬에서 만든 문서를 세상에 내보냅니다. requirements.txt로 의존성을 고정하고, GitHub에 올려 Cloudflare Pages에 연결하고, 커스텀 도메인을 붙이는 과정을 정리하겠습니다. MkDocs 기본 배포인 gh-deploy도 함께 짚습니다.
MkDocs로 매뉴얼 만들기 #3 콘텐츠 작성 — 코드블록, Mermaid, admonition
문서를 읽기 좋게 만드는 세 가지 요소를 다룹니다. 제목, 줄 강조가 붙는 코드블록, 코드로 그리는 Mermaid 다이어그램, 그리고 주의, 경고를 눈에 띄게 보여 주는 admonition까지 MkDocs Material에서 쓰는 법을 정리하겠습니다.
MkDocs로 매뉴얼 만들기 #2 nav와 검색 — 문서의 정보 구조 잡기
문서가 수십 편으로 늘어도 독자가 길을 잃지 않으려면 사이드바와 검색이 핵심입니다. MkDocs에서 nav를 mkdocs.yml에 직접 설계하고, Material의 내비게이션 기능과 내장 검색을 켜는 데까지 정리하겠습니다.
MkDocs로 매뉴얼 만들기 #1 설치부터 첫 문서까지
MkDocs와 Material 테마로 팀 문서, 제품 매뉴얼 사이트의 뼈대를 세웁니다. Python 가상환경에 설치하는 것부터 새 사이트 생성, 테마 적용, 로컬 서버로 첫 문서를 띄우는 데까지 한 번에 진행하겠습니다.