정적 블로그는 배포가 단순하다. 파일을 빌드해서 정적 호스팅에 올리면 된다. 그런데 단순하다는 이유로 확인 과정을 생략하면, 오타보다 먼저 깨진 링크와 빌드 오류가 방문자를 만난다.

그래서 이 블로그는 글을 쓰는 흐름을 두 단계로 나눴다.

먼저 빌드하고, 그다음 공개한다

Pull Request가 열리거나 갱신되면 pnpm docs:build를 실행한다. VitePress가 모든 페이지를 렌더링하고 내부 링크를 확인하므로, 글을 올리기 전에 사이트 전체가 만들어지는지 알 수 있다.

pnpm install --frozen-lockfile도 함께 사용한다. 로컬에서 우연히 설치된 버전이 아니라 lockfile에 기록된 의존성으로 빌드해야 CI와 실제 배포 환경의 차이가 줄어든다.

main은 공개 배포의 경계로 둔다

검증을 통과한 변경이 main에 들어오면 Pages 배포 워크플로가 같은 빌드를 다시 만들고, 결과물을 GitHub Pages에 올린다. 글을 추가한 커밋도, 디자인을 고친 커밋도 같은 경로를 탄다.

Pull Request → build · dead-link check
                    ↓
              merge to main
                    ↓
          build → upload artifact → Pages

이 구조에서 CI의 역할은 “배포가 됐다”고 말하는 것이 아니라, 공개할 수 있는 결과물이 만들어지는지 확인하는 데 있다. 배포는 main에 반영된 변경만 대상으로 삼는다.

글을 쓰는 사람에게 남는 것

새 글은 docs/posts/<slug>.md 파일 하나로 시작한다. frontmatter의 날짜와 제목을 기준으로 홈의 최근 기록, 글 아카이브, RSS가 자동으로 갱신된다.

결국 필요한 습관은 크지 않다.

1. 글을 추가한다.
2. 로컬에서 pnpm docs:build를 실행한다.
3. PR을 열고 검증 결과를 확인한다.
4. main에 반영한다.

기록을 계속 남기려면 글쓰기 자체의 마찰이 낮아야 한다. 동시에 공개된 페이지는 언제나 빌드 가능한 상태여야 한다. 이 정도의 작은 자동화가 두 가지를 같이 지켜준다.