기술블로그 배포 전에 자동으로 검증하는 것들
핵심 요약
개인 기술블로그라도 배포 전 검증 기준이 있어야 한다. 글 하나가 깨진 링크나 잘못된 frontmatter를 포함하면 검색 인덱스, RSS, sitemap, 빌드 결과까지 함께 흔들릴 수 있기 때문이다.
이 저장소의 기준 명령은 npm run check다. strict sync, 테스트, audit, build를 한 번에 실행해서 콘텐츠 파이프라인과 Docusaurus 빌드가 같이 통과하는지 확인한다.
문제 상황
블로그 배포 실패는 코드 변경에서만 생기지 않는다. Markdown 문서 하나에 잘못된 wiki link가 남아 있어도 공개 페이지의 연결성이 깨진다. 같은 slug를 가진 글이 두 개 생기면 canonical URL과 sitemap 신뢰도가 떨어진다.
반복 검증을 사람이 기억에 의존해서 실행하는 것도 위험하다. 글을 빠르게 수정한 뒤 바로 배포하면 draft 글이 검색 인덱스에 들어가거나, description이 비어 있는 글이 sitemap에 포함될 수 있다.
설계 방식
검증은 네 단계로 나눴다.
첫 번째는 npm run sync:strict다. 이 단계는 Obsidian Markdown을 Docusaurus 글로 정규화하면서 slug 충돌, broken wiki link, 처리 실패, description 부족, tags 누락, category 누락을 검사한다.
두 번째는 npm test다. sync 로직의 순수 함수와 파이프라인 흐름을 Vitest로 검증한다. 이 테스트는 실제 posts/를 망가뜨리지 않도록 임시 디렉터리를 사용한다.
세 번째는 npm run audit다. 전체 의존성 audit을 실행해 보안 취약점을 확인한다. 운영 상황에서 배포 산출물 기준만 보고 싶을 때는 npm run audit:prod를 별도로 사용할 수 있다.
네 번째는 npm run build다. Docusaurus가 RSS, Atom, sitemap, 검색 인덱스, 정적 HTML을 모두 생성할 수 있는지 확인한다.
검증 방법
로컬에서는 다음 순서로 확인한다.
npm ci
npm run sync:strict
npm test
npm run audit
npm run build
npm run check
GitHub Actions에서는 같은 기준을 더 단순하게 적용한다. 의존성 설치 후 npm run check만 실행하게 해서 로컬과 CI의 기준을 맞춘다.
빌드 결과는 build/sitemap.xml, build/robots.txt, build/llms.txt, 글 HTML의 canonical/OG/Twitter/JSON-LD를 함께 확인한다. 이 검증은 검색 엔진과 AI 검색이 사이트 구조를 올바르게 읽는지 확인하기 위한 최소 기준이다.
개선 방향
앞으로는 검증 결과를 더 읽기 좋은 리포트로 만들 수 있다. 예를 들어 broken wiki link, slug 충돌, description 품질 문제를 Markdown 리포트로 남기면 PR에서 바로 확인할 수 있다.
또한 Lighthouse나 HTML validator를 CI에 추가하면 성능과 접근성까지 같은 흐름에서 점검할 수 있다. 다만 개인 블로그에서는 우선 빌드 안정성과 콘텐츠 메타데이터 신뢰도를 먼저 고정하는 것이 효과가 크다.