MkDocs로 매뉴얼 만들기 #1 설치부터 첫 문서까지

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

문서를 처음 체계적으로 만들다 보면 거의 예외 없이 같은 문제를 만납니다. README 한 장으로는 감당이 안 되는 문서를 어디에 쌓을 것인가 하는 문제입니다. 노션은 외부 공개와 버전 관리가 번거롭고, 블로그 도구로 만들면 글이 시간순으로 나열될 뿐 레퍼런스로 쓰기 불편합니다. 그래서 많은 팀이 문서를 코드처럼 다루는 방식, 곧 Docs as Code로 옮겨 갑니다. 마크다운으로 쓰고, Git으로 관리하고, 정적 사이트로 배포하는 방식입니다.

이 시리즈는 그 첫 단추인 정적 사이트 생성기로 문서 사이트를 짓는 법을 다룹니다. 도구는 MkDocs입니다. Python으로 만들어졌고 설정이 간단해, 특히 이미 Python을 쓰는 팀이라면 진입 장벽이 가장 낮은 선택입니다. 테마는 문서에 특화된 Material for MkDocs를 씁니다.

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

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

이번 글은 MkDocs가 무엇을 준비물로 요구하는지, 그리고 새 사이트를 만들어 Material 테마를 적용하고 로컬에서 첫 문서를 띄우는 데까지를 직접 실행해 보며 마무리하겠습니다.

준비물 — Python 하나면 됩니다 #

MkDocs는 Python 패키지입니다. 그래서 준비물도 단순합니다. Python 3와 pip만 있으면 됩니다. Hugo가 단일 바이너리에 Go까지 챙겨야 했던 것과 달리, 이미 Python이 깔린 환경이라면 바로 시작할 수 있습니다.

설치 #

설치는 프로젝트별 가상환경(venv) 안에서 하는 것을 권합니다. 시스템 Python을 더럽히지 않고, 문서 도구 버전을 프로젝트마다 따로 관리할 수 있기 때문입니다.

설치 (가상환경 권장) 
# 프로젝트 폴더에서 가상환경 생성과 활성화
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

# Material 테마 설치 (mkdocs 본체도 함께 깔립니다)
pip install mkdocs-material

mkdocs-material을 설치하면 MkDocs 본체가 의존성으로 함께 설치됩니다. 설치 후 버전을 확인합니다.

버전 확인 
mkdocs --version

새 사이트 만들기 #

빈 문서 사이트의 뼈대를 만듭니다. 현재 폴더에 그대로 생성하려면 점(.)을 인자로 줍니다.

새 사이트 생성 
mkdocs new .

이 명령은 두 가지를 만듭니다. 설정 파일 mkdocs.yml과, 첫 문서가 들어 있는 docs/index.md입니다. 문서는 모두 docs 폴더 안에 쌓입니다.

Material 테마 적용 #

생성된 mkdocs.yml을 열어 테마를 Material로 지정합니다. 기본값은 밋밋한 내장 테마라, 이 한 줄을 바꾸는 것만으로 검색, 다크 모드, 반응형이 갖춰진 문서 사이트가 됩니다.

mkdocs.yml 
site_name: 제품 매뉴얼
theme:
  name: material

첫 문서 띄우기 #

이제 로컬 서버를 띄웁니다. 파일을 고치면 화면이 자동으로 새로고침됩니다.

로컬 서버 실행 
mkdocs serve

브라우저에서 http://127.0.0.1:8000을 열면 Material 레이아웃에 첫 문서가 나타납니다. 문서를 한 편 더 추가해 보겠습니다. docs 폴더에 파일을 만들면 됩니다.

문서 추가 
# docs/getting-started.md 를 만들어 본문을 채웁니다

폴더 구조 이해하기 #

지금까지 만들어진 구조에서 당장 알아야 할 것은 docs 한 곳과 설정 파일입니다.

폴더 구조 
my-docs/
├─ mkdocs.yml         # 사이트 설정
├─ docs/              # 문서 본문 (여기만 채우면 됩니다)
│  ├─ index.md        # 첫 화면
│  └─ getting-started.md
└─ site/              # mkdocs build 산출물 (배포용)

문서를 늘리는 일은 결국 docs 아래에 마크다운 파일을 더하는 일입니다. 다만 Hugo가 폴더 구조를 그대로 사이드바로 삼았던 것과 달리, MkDocs는 사이드바(nav)를 mkdocs.yml에 직접 적어 순서와 묶음을 정합니다. 그 방법은 다음 편에서 본격적으로 다룹니다.

마무리 #

이번 글에서는 Python 가상환경에 MkDocs Material을 설치하고, 새 사이트에 테마를 적용해 로컬에서 첫 문서를 띄우는 데까지 마쳤습니다. 설정 파일 한 줄로 검색까지 갖춘 문서 사이트가 시작된다는 점이 MkDocs의 가장 큰 장점입니다.

다음 편에서는 nav와 검색을 다룹니다. 문서가 수십 편으로 늘어도 독자가 길을 잃지 않도록, mkdocs.yml로 정보 구조를 설계하는 단계입니다.

X