GitHub Pages에서 Jekyll 빌드 실패? 로컬 환경 설정이 정답입니다

처음 마주한 당황스러운 순간

컴퓨터공학과를 정년퇴직한 지 3년째, 이제야 제 자신을 위한 블로그를 만들기로 결심했습니다. 예전엔 학생들에게 GitHub와 Jekyll을 가르쳤지만, 정작 직접 해본 건 오래됐거든요. GitHub Pages에 올렸다고 생각했는데 빌드 실패 이메일이 날아왔을 때의 그 기분, 잊을 수가 없습니다.

“아, 시대가 많이 변했구나”라고 실감했습니다. 2023년 이후로 Ruby 버전이 올라갔고, Jekyll의 의존성도 복잡해졌거든요. 저는 여러 날 밤을 새워가며 문제를 파헤쳤고, 결국 깨달은 게 하나 있습니다. GitHub Pages에 직접 올리기 전에 로컬 환경에서 완벽히 테스트하는 것이 얼마나 중요한지 말이죠.

로컬 환경 설정: 성공의 첫 번째 열쇠

먼저 Ruby 버전을 확인해야 합니다. 최신 GitHub Pages는 Ruby 3.1 이상을 권장합니다. 저는 처음에 Mac에 깔려있던 구형 Ruby로 시작했다가 삽질을 했습니다. ruby --version으로 확인하고, 필요하면 rbenv나 rvm으로 버전을 업그레이드하세요.

다음은 Bundler를 통한 의존성 관리입니다. 저는 이 부분을 무시했다가 큰 코를 다쳤습니다. GitHub Pages가 사용하는 정확한 gem 버전을 맞춰야 로컬과 서버 환경이 동일해집니다. Gemfile에는 반드시 이렇게 작성하세요:

source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins

그리고 bundle install을 실행합니다. 이것만으로도 여러분은 저처럼 며칠을 헤매지 않을 겁니다. 번들러는 정확한 버전 조합을 Gemfile.lock에 기록하고, 로컬과 GitHub 서버가 동일한 환경을 유지하게 됩니다.

Jekyll 로컬 서버에서 미리보기하기

로컬 설정이 끝났으면 이제 정말 중요한 부분입니다. 매번 GitHub에 푸시한 후 빌드 결과를 기다릴 필요가 없습니다. 로컬에서 bundle exec jekyll serve를 실행하면, localhost:4000에서 즉시 블로그를 미리볼 수 있습니다.

저는 이 명령어의 진가를 깨달았을 때 정말 감동했습니다. 마크다운 문법 오류, 레이아웃 문제, 플러그인 호환성까지 모든 것을 로컬에서 확인하고 수정할 수 있거든요. 특히 Chirpy 테마처럼 복잡한 테마를 쓸 때는 이것이 필수입니다.

_config.yml 파일도 로컬에서 여러 번 수정해보세요. 블로그 제목, 로고, 카테고리 설정 등이 즉시 반영되는 모습을 보면 정말 신기합니다. 그리고 여러분은 확신을 갖고 GitHub에 푸시할 수 있게 됩니다.

GitHub 저장소 설정과 주의사항

GitHub 저장소 이름을 username.github.io 형식으로 해야 한다는 건 기본입니다. 저도 처음엔 이걸 놓쳤거든요. 대신 저처럼 실수하는 분들을 위해 한 가지 팁을 더 알려드립니다.

저장소의 Settings에서 Pages 섹션을 확인하세요. Branch를 main이나 master로, 폴더를 / (root)로 설정해야 합니다. 그리고 반드시 로컬에서 bundle exec jekyll build로 빌드해본 후, _site 폴더에 오류가 없는지 확인하고 푸시하세요.

한 가지 더, .gitignore 파일을 꼭 확인하세요. _site/ 폴더는 GitHub Pages에서 자동으로 생성되므로 커밋할 필요가 없습니다. 로컬에서만 가지고 있으면 됩니다.

저는 60을 넘어서 이 기술들을 다시 배웠습니다. 시간이 오래 걸렸지만, 이제 확신합니다. 여러분은 저처럼 시행착오를 거치지 않고도 완벽하게 설정할 수 있습니다. 오늘 바로 로컬 환경을 설정하고, bundle exec jekyll serve를 실행해보세요. 그리고 댓글이나 이메일로 여러분의 블로그 설정 경험을 공유해주시면 정말 감사하겠습니다.