MkDocs로 매뉴얼 만들기 #4 Cloudflare Pages로 배포하고 도메인 연결하기

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

#3까지 오면 로컬에서 보기 좋은 문서가 갖춰집니다. 하지만 localhost는 나만 볼 수 있습니다. 이번 글에서는 이 문서를 누구나 주소로 접속할 수 있게 내보냅니다.

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

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

이번 글은 의존성을 고정해 GitHub에 올리고, Cloudflare Pages에 연결해 빌드를 잡고, 커스텀 도메인을 붙이는 데까지 다루겠습니다.

의존성을 고정한다 — requirements.txt #

빌드 서버가 내 컴퓨터와 같은 버전으로 문서를 만들게 하려면, 쓰는 패키지를 적어 둬야 합니다. 이게 requirements.txt입니다.

requirements.txt 
mkdocs-material

버전을 더 엄격히 고정하려면 mkdocs-material==9.5.0처럼 적습니다. 이 파일이 있어야 빌드 서버가 같은 도구를 설치해 같은 결과를 냅니다.

GitHub에 올리기 #

빌드 결과물은 저장소에 넣지 않도록 .gitignore부터 만듭니다. MkDocs의 빌드 산출물은 site 폴더입니다.

.gitignore 
site/

그다음 저장소를 초기화해 푸시합니다.

GitHub에 올리기 
git init
git add .
git commit -m "docs: 첫 문서"
git branch -M main
git remote add origin https://github.com/내계정/my-docs.git
git push -u origin main

Cloudflare Pages에 연결 #

Cloudflare 대시보드에서 Workers & Pages → Create → Pages → Connect to Git로 저장소를 선택합니다. MkDocs는 Python이라 빌드 명령에서 의존성을 먼저 설치해야 합니다.

항목값
빌드 명령pip install -r requirements.txt && mkdocs build
빌드 출력 디렉터리site
환경 변수PYTHON_VERSION = 3.12

Save and Deploy를 누르면 첫 배포가 시작되고, 끝나면 프로젝트이름.pages.dev 주소가 생깁니다. 이후로는 main에 푸시할 때마다 자동으로 다시 빌드됩니다.

더 간단한 길 — gh-deploy #

GitHub Pages를 쓴다면 MkDocs가 배포까지 한 명령으로 해 줍니다. 빌드한 결과를 gh-pages 브랜치에 올리는 방식입니다.

GitHub Pages로 한 번에 
mkdocs gh-deploy

손이 가장 적게 가지만, 빌드를 내 컴퓨터에서 직접 돌려 올린다는 점이 Cloudflare 연동과 다릅니다. 팀이 함께 쓴다면 푸시 시 자동 빌드되는 Cloudflare 쪽이 사고가 적습니다.

커스텀 도메인 연결 #

pages.dev 주소 대신 직접 산 도메인을 붙입니다. Pages 프로젝트의 Custom domains → Set up a domain에서 도메인을 입력합니다. 다른 곳에서 DNS를 관리한다면 다음 레코드를 직접 넣습니다.

DNS 레코드 (하위 도메인) 
유형    이름     값
CNAME   docs     프로젝트이름.pages.dev

연결이 끝나면 HTTPS 인증서는 Cloudflare가 자동으로 발급하고 갱신합니다.

마무리 #

이번 글에서는 requirements.txt로 의존성을 고정해 GitHub에 올리고, Cloudflare Pages에 연결해 빌드를 잡고, 커스텀 도메인까지 붙였습니다. 이제 문서는 진짜 주소를 갖고 인터넷에 떠 있습니다.

다음 편에서는 다국어와 버전 관리를 다룹니다. 하나의 문서를 여러 언어로 제공하고, 제품 버전이 올라갈 때 옛 문서를 어떻게 함께 유지할지 정리하겠습니다.

X