WordPress에서 Jekyll로 이전하기 (그리고 정적 사이트 생성기 일반에 대해)

DemandSphere는 WordPress에서 Jekyll로 사이트를 이전했다. 핵심 이유는 속도, 수정 용이성, 그리고 빠르게 움직이는 팀에 맞는 더 단순한 운영 방식이었다.

정적 사이트 생성기(SSG)는 데이터베이스와 애플리케이션 서버 대신 HTML 템플릿, include, layout, config, markdown 중심으로 동작한다. 게시글 메타데이터는 파일 상단의 frontmatter YAML에 넣고, 글은 _drafts에서 시작해 _posts로 옮겨 발행한다.

마이그레이션 대상은 288개 WordPress 게시물과 기타 페이지였다. 15년치 아카이브 전체를 옮기기보다, GSC 데이터와 인덱싱 가치를 기준으로 유지할 페이지를 추렸고, 가치가 낮은 페이지는 제거하거나 비색인 처리했다. WordPress의 XML export를 활용해 콘텐츠와 이미지를 옮겼다.

이 작업의 실질적인 가속기는 Claude Code였다. 팀은 여러 세션과 여러 개의 .md 파일, CLAUDE.md를 함께 써서 작업 맥락을 유지했고, 사람이 하기엔 시간이 많이 드는 분석과 정리를 에이전트가 맡았다.

레포 안에는 운영용 dev tools 9개를 직접 만들었다. 대표적으로:

• Site Structure: sitemap 누락, 중복 메타데이터, 잘못된 폴더 배치를 탐지
• Lighthouse Auditor: 성능뿐 아니라 SEO 관점의 품질 점검
• Schema Auditor / Schema Details: 구조화 데이터의 기본 커버리지와 페이지별 보강 포인트 확인
• AEO Auditor: 답변 엔진 최적화의 기초 점검
• Open Graph Preview: Facebook, LinkedIn, X, Slack 공유 미리보기
• Content Similarity 도구들: 임베딩 기반 토픽 클러스터, 유사 문서, semantic core 분석
• Internal Linking: 임베딩을 바탕으로 주제 간 내부 링크 개선
• Redirects: 컷오버 후 리디렉션 누락 방지

사이트 전체는 all-MiniLM-L6-v2 임베딩 모델을 @xenova/transformers로 로컬 실행해 벡터화했다. 이를 바탕으로 토픽 테이블, 유사도 보고서, semantic core 분석까지 확장했다.

SEO 쪽에서는 처음부터 JSON-LD를 전 페이지에 적용했다. Organization, WebSite, BreadcrumbList, FAQPage, BlogPosting, SoftwareApplication 등을 템플릿과 frontmatter로 자동 생성했고, FAQ는 YAML의 faq_schema 블록에서 자동 처리했다. 사이트맵은 jekyll-sitemap 플러그인으로 생성했다.

또한 CSP 조정에 시간이 많이 들었다. Cloudflare 분석 비콘, Google Ads 전환 추적, Leaflet 지도 등에서 차례로 차단 문제가 생겨 약 6차례 정책 업데이트를 거쳤다.

배포는 Cloudflare Pages에서 진행했다. main은 production, 다른 브랜치는 preview로 동작하며, CF_PAGES_BRANCH를 보고 JEKYLL_ENV를 바꿨다. production은 dev-tools를 제외하고 sitemap을 유지했고, staging은 sitemap을 제거하고 noindex를 적용했다. DNS도 Cloudflare에서 관리해 커트오버가 수월했다.

컷오버 이후에는 몇 가지 후속 수정도 했다. 예를 들어 Google 검색 결과용 favicon이 안 보였는데, 원인은 /favicon.ico 404와 32x32 PNG만 있던 점이었다. 이를 96x96 PNG, 48x48 PNG, web manifest, multi-size ICO로 정리했다.

지금도 할 일은 남아 있다. 100KB 이상 이미지 약 65개를 더 최적화해야 하고, 288개 마이그레이션 글의 태깅도 더 정교하게 해야 한다. 그래도 전체적으로는 더 빠르게, 더 높은 품질로 새 콘텐츠를 만들 수 있는 기반을 갖췄다.