블로그 초기 환경 세팅

이 문서는 Python 기반 정적 사이트 생성기인 MkDocs 프로젝트를 처음 클론받아 로컬 환경을 구성하고 구동하기 위한 상세 매뉴얼입니다.

본 프로젝트는 DevOps 관점에서의 일관성(Idempotency)을 유지하기 위해 기존 pip 대신 uv를 사용하여 패키지 의존성과 가상환경을 엄격하게 격리하고 관리합니다.

1. 시스템 요구사항 및 사전 준비

프로젝트를 실행하기 전, 로컬 PC에 다음 환경이 구성되어 있어야 합니다.

Git: 저장소 관리를 위한 필수 도구
Python: 3.14.6 버전 (이 프로젝트는 .python-version 파일을 통해 해당 버전을 강제합니다.)
uv: 초고속 파이썬 패키지 및 프로젝트 관리자
설치 명령어 (macOS/Linux): curl -LsSf https://astral.sh/uv/install.sh | sh
설치 명령어 (Windows): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

이 블로그를 구성하기 위해 pyproject.toml과 uv.lock에 정의된 핵심 패키지들은 다음과 같습니다.

mkdocs: Markdown 파일을 HTML로 빌드하는 코어 정적 사이트 생성 프레임워크입니다.
mkdocs-material[imaging]: 반응형 UI, 다크모드, 검색 기능 등을 제공하는 최상위 테마입니다. [imaging] 옵션이 포함되어 있어 다이어그램(Mermaid) 처리를 지원합니다.
mkdocs-awesome-pages-plugin: mkdocs.yml을 수동으로 수정하지 않아도, 폴더 구조를 기반으로 네비게이션(메뉴)을 자동 생성해 주는 플러그인입니다.

새로운 작업 환경에서 블로그 저장소를 내려받고, 완전히 동일한 패키지 버전을 세팅하는 과정입니다.

터미널을 열고 아래 명령어를 통해 프로젝트를 로컬로 가져옵니다.

git clone [https://github.com/](https://github.com/)<본인-계정>/<리포지토리명>.git
cd <리포지토리명>

uv를 사용하여 가상환경(.venv)을 만들고 패키지를 설치합니다.

uv sync

동작 원리: uv sync 명령어는 저장소에 커밋된 uv.lock 파일을 읽어들여, 다른 PC나 배포 서버에서도 100% 동일한 패키지 환경이 구축되도록 보장합니다.

글을 작성하거나 설정을 변경할 때, 배포 전 로컬에서 실시간으로 렌더링 결과를 확인합니다.

아래 명령어를 입력하여 로컬 서버를 구동합니다.

uv run mkdocs serve

서버 접속: 구동 성공 시 브라우저에서 http://127.0.0.1:8000으로 접속합니다.
Live Reload: 서버가 켜진 상태에서 .md 파일이나 .pages 파일을 수정하고 저장하면, 터미널이 변경을 감지하고 브라우저를 자동으로 새로고침합니다.
서버 종료: 터미널에서 Ctrl + C를 입력합니다.

이 블로그는 GitHub main 브랜치에 코드가 Push 되면 Cloudflare Pages를 통해 자동으로 빌드 및 배포되도록 구성되어 있습니다.

만약 Cloudflare 연동을 새로 해야 한다면 아래의 설정값을 정확히 입력해야 합니다.

pip install uv && uv sync && uv run mkdocs build

(해설: Cloudflare의 기본 리눅스 컨테이너에 uv를 설치한 뒤, uv.lock을 동기화하여 환경을 구성하고 최종 HTML 파일을 빌드합니다.)