문서 사이트: MkDocs + Cloudflare Pages¶

맥락¶

프로젝트 문서(ADR, Runbook, Data Catalog)가 늘어나면서 마크다운 파일만으로는 탐색이 어려워졌다. 문서 사이트를 구축하되, 레포를 private으로 전환할 예정이므로 private repo를 무료로 지원하는 호스팅이 필요하다.

결정¶

MkDocs (Material 테마) 로 정적 사이트를 생성하고, Cloudflare Pages에 무료로 호스팅한다.

아키텍처¶

전체 흐름¶

개발자가 docs/*.md 수정 → main push
    │
    ▼
GitHub Actions (.github/workflows/docs.yml)
    │  1. actions/checkout — 소스 체크아웃
    │  2. actions/setup-python — Python 3.11 설치
    │  3. pip install mkdocs-material — MkDocs + Material 테마 설치
    │  4. mkdocs build --strict — docs/*.md → site/*.html 변환
    │  5. wrangler pages deploy — site/ 폴더를 Cloudflare에 업로드
    ▼
Cloudflare Pages (CDN)
    │  정적 HTML/CSS/JS를 전 세계 300+ 엣지 노드에 캐싱
    ▼
https://trend-collector-docs.pages.dev
    사용자 접속 → 가장 가까운 CDN 노드에서 응답

빌드 과정 상세¶

docs/                          site/ (빌드 결과물)
├── index.md            ──▶    ├── index.html
├── adr/                       ├── adr/
│   ├── 001-*.md        ──▶    │   ├── 001-*/index.html
│   └── ...                    │   └── ...
├── runbook/                   ├── runbook/
│   ├── operations.md   ──▶    │   ├── operations/index.html
│   └── ...                    │   └── ...
└── data-catalog/              ├── data-catalog/
    ├── sources.md      ──▶    │   ├── sources/index.html
    └── ...                    │   └── ...
                               ├── assets/     (CSS, JS, 폰트)
                               ├── search/     (검색 인덱스)
                               └── sitemap.xml

구성 요소¶

구성 요소	역할	비용
MkDocs	마크다운 → HTML 변환 (정적 사이트 생성기)	무료 (OSS)
Material for MkDocs	테마 (검색, 다크모드, 코드 하이라이트)	무료 (OSS)
GitHub Actions	CI/CD (빌드 + 배포 자동화)	무료 (public repo 무제한, private 2000분/월)
Cloudflare Pages	정적 파일 호스팅 + CDN	무료 (500빌드/월, 대역폭 무제한)
pages.dev 도메인	자동 발급 서브도메인	무료

파일 구성¶

trend-collector/
├── mkdocs.yml                        # MkDocs 설정 (테마, 네비게이션, 플러그인)
├── docs/                             # 마크다운 소스
│   ├── index.md                      # 홈페이지
│   ├── architecture/overview.md      # 아키텍처 개요
│   ├── adr/                          # Architecture Decision Records
│   ├── runbook/                      # 운영 매뉴얼
│   └── data-catalog/                 # 데이터 명세서
├── .github/workflows/docs.yml       # 자동 빌드 + 배포 워크플로우
└── site/                             # 빌드 결과물 (.gitignore)

GitHub Secrets¶

Secret	용도
`CLOUDFLARE_ACCOUNT_ID`	Cloudflare 계정 식별자
`CLOUDFLARE_API_TOKEN`	Cloudflare Pages 편집 권한 토큰

워크플로우 트리거 조건¶

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'       # 문서 내용 변경 시
      - 'mkdocs.yml'    # 설정 변경 시
  workflow_dispatch:     # 수동 실행

docs/ 또는 mkdocs.yml이 변경된 main push에서만 실행. 소스 코드만 변경된 경우 빌드하지 않음.

근거¶

무료: 정적 파일만 CDN에 올리는 구조라 서버 비용이 없다. Cloudflare는 이를 유료 서비스(Workers, R2) 유입 경로로 활용하여 무료 제공.
Private repo 지원: GitHub Pages 무료 플랜은 public repo만 지원. Cloudflare Pages는 제한 없음.
자동 배포: docs 변경 → push → 자동 빌드 + 배포. 수동 작업 불필요.
성능: 전 세계 300+ CDN 노드에서 서빙. 별도 서버 운영보다 빠름.
기존 인프라 활용: Cloudflare에 이미 haotoday.com이 등록되어 있어 커스텀 도메인 연결 용이.

검토한 대안¶

대안	장점	선택하지 않은 이유
GitHub Pages	GitHub 네이티브, 설정 간단	Private repo에서 무료 사용 불가 (Pro $4/월 필요)
Netlify	무료, private repo 지원	Cloudflare에 이미 도메인 있어 통합 관리 유리
Vercel	무료, 빌드 빠름	정적 사이트에 과도한 기능, Cloudflare 통합 불가
자체 서버 (Nginx)	완전 제어	서버 관리 부담, CDN 없음, 비용 발생

결과¶

문서 사이트: https://trend-collector-docs.pages.dev
문서 변경 시 main push만으로 자동 배포
커스텀 도메인 연결 가능 (예: docs.haotoday.com)
월 500회 빌드 무료 (현재 사용량 대비 충분)