블로그 초기 환경 세팅¶

이 블로그는 Markdown을 HTML로 바꾸는 MkDocs와 Material 테마를 사용한다. 로컬에서 글을 작성하고 미리본 뒤, 정적 파일을 Cloudflare Pages에 배포하는 구성이다.

실행 환경과 패키지¶

Git, uv
Python 3.14.6: .python-version에 지정된 프로젝트 실행 버전
MkDocs 1.6.1, Material 9.7.6, awesome-pages 2.10.1: 현재 uv.lock에 기록된 버전

pyproject.toml은 Python 하한을 >=3.14.6으로 선언하고, .python-version은 uv가 프로젝트에서 사용할 버전을 지정한다. uv.lock은 해결된 패키지 버전을 기록한다. OS·CPU별 패키지나 외부 도구까지 모든 환경이 완전히 같아지는 것은 아니다.

Material의 [imaging] extra는 이미지 처리 관련 의존성이다. Mermaid는 이 옵션으로 활성화되는 것이 아니라 pymdownx.superfences의 Mermaid 설정으로 처리된다.

저장소 준비¶

git clone https://github.com/gyubeom-j/blog.git
cd blog
uv sync --locked

--locked는 lock 파일을 변경하지 않고 동기화하도록 한다. 의존성 선언과 lock 파일이 맞지 않으면 오류를 확인하고 먼저 정리한다. 필요한 Python이 없다면 uv가 관리하는 Python을 다운로드할 수 있다.

로컬 미리보기¶

uv run --locked mkdocs serve --dev-addr 127.0.0.1:8000

로컬 미리보기에 접속한다. 파일을 저장하면 미리보기가 갱신된다. Ctrl+C로 종료하며, 포트가 사용 중이면 끝의 8000을 8001로 바꾼다.

배포 전 빌드¶

uv run --locked mkdocs build --strict

site/에 HTML과 정적 자산을 생성한다. --strict는 경고가 있을 때 빌드를 실패시킨다. 링크·메뉴·이미지 경로를 확인한 뒤 브라우저에서 모바일 메뉴, 다크 모드, 코드 블록과 그래프도 확인한다.

Cloudflare Pages 배포 설정¶

기존 운영 기록의 배포 대상은 Cloudflare Pages다. 실제 Git 연동 상태와 배포 브랜치는 대시보드에서 확인해야 한다.

pip install uv && uv sync --locked && uv run --locked mkdocs build --strict

Build output directory: site
프로젝트 Python 버전: 3.14.6 (.python-version)
기존 문서에 기록된 Cloudflare 환경변수: PYTHON_VERSION=3.14. 이것이 uv의 정확한 프로젝트 버전을 대신하지는 않는다.

Git 연동이 활성화된 환경에서는 배포 브랜치로 Push하면 배포가 시작될 수 있다. 로컬 미리보기와 빌드만으로는 공개 사이트가 바뀌지 않는다.