GitHub Pages에서 Jekyll 테마 커스터마이징할 때 겪은 5가지 함정

프롤로그: 은퇴 후 시작한 블로깅 여정

저는 40년을 대학에서 컴퓨터공학을 가르치다 작년 정년퇴직했습니다. 은퇴 후 그동안 못했던 기술 블로깅을 시작하려고 WordPress나 Medium을 고려했지만, 결국 개발자다운 방식으로 GitHub Pages와 Jekyll을 선택했습니다. 특히 세련된 Chirpy 테마에 매료되어 바로 시작했는데, 예상 외의 난관들이 많았습니다. 오늘은 제 실제 경험담을 통해 후배 개발자들이 같은 실수를 하지 않길 바라는 마음으로 이 글을 씁니다.

첫 번째 함정: 로컬 환경과 배포 환경의 Ruby 버전 차이

처음 Chirpy를 로컬에 설치했을 때는 bundle exec jekyll serve로 완벽하게 작동했습니다. 그런데 GitHub Actions를 통해 배포된 사이트는 CSS가 깨져 보였습니다. 한 시간을 디버깅한 끝에 깨달은 것은 제 로컬 Ruby 버전이 3.2였는데 GitHub Actions의 기본 Ruby가 2.7이었다는 것입니다.

Gemfile에 명시적으로 Ruby 버전을 지정하지 않으면 이런 문제가 발생합니다. 해결책은 간단했습니다. Gemfile의 맨 첫 줄에 ruby '3.2.0'을 추가하고, .github/workflows 디렉토리의 yml 파일을 확인하여 ruby-version을 명시적으로 설정했습니다. 이후 GitHub Actions 워크플로우도 동일한 환경에서 빌드되어 배포 후 결과물이 로컬과 정확히 일치했습니다.

여러분도 로컬에서 완벽하게 작동하는 사이트가 배포되면 달라진다면, 먼저 환경 설정을 의심해보시기 바랍니다.

두 번째 함정: _config.yml의 baseurl 설정 오류

Chirpy 설치 후 제가 한국어 글을 쓰기 위해 플러그인을 추가했는데, 갑자기 모든 이미지와 CSS 링크가 404 에러를 뱉었습니다. 처음엔 플러그인 때문이라고 생각했지만, 실제 원인은 _config.yml의 baseurl 설정이었습니다.

저는 저장소 이름을 my-blog로 만들었는데, GitHub Pages에서는 사용자 이름이 아닌 프로젝트 저장소면 baseurl을 /my-blog로 설정해야 합니다. 하지만 저는 이를 놓쳤고, baseurl: ""로 비워두었던 것입니다. 이로 인해 Jekyll이 생성한 모든 자산의 경로가 잘못되었습니다. 정확하게 설정한 후에야 모든 것이 제대로 로드되었습니다.

배포 구조에 따라 baseurl을 다르게 설정해야 한다는 점, 꼭 기억하시길 바랍니다. 사용자.github.io 저장소면 비우고, 프로젝트 저장소면 저장소 이름을 슬래시와 함께 입력하세요.

세 번째 함점: 포스트 파일명과 frontmatter의 날짜 불일치

저는 아침에 작성한 글을 파일명으로는 2026-05-18-my-post.md라 했는데, 실수로 frontmatter의 date 필드에 2026-05-17을 입력했습니다. 그 결과 포스트가 아예 노출되지 않았습니다. Jekyll은 기본적으로 미래 날짜의 포스트를 발행하지 않으며, 파일명의 날짜와 frontmatter 날짜가 불일치하면 예상치 못한 동작이 발생할 수 있습니다.

Chirpy 테마의 경우 파일명 날짜를 기준으로 하기 때문에, frontmatter의 날짜와 일치시키는 것이 중요합니다. 저는 이후 자신의 블로그 포스팅 프로세스에서 항상 날짜를 먼저 확인하는 체크리스트를 만들었습니다.

결론 및 실천 방안

제 경험상 Jekyll 블로깅의 80%의 문제는 환경 설정과 간단한 설정 오류입니다. 로컬과 배포 환경의 일관성 유지, baseurl 정확한 설정, 날짜 관리의 엄격함이 안정적인 블로깅을 위한 삼대 원칙이라고 생각합니다. 처음부터 이 세 가지만 제대로 설정했다면 많은 시간을 낭비하지 않았을 것입니다.

혹시 Jekyll 블로깅 중 유사한 문제를 겪고 계신다면, 제 경험담이 도움이 되길 바랍니다. 댓글로 여러분의 경험담도 공유해주세요. 함께 배우고 성장하는 개발자 커뮤니티가 되길 희망합니다.