GitHub Pages에서 블로그가 자꾸 깨지는 이유? Jekyll 빌드 에러 완벽 해결법

안녕하세요. 저는 컴퓨터과학과 명예교수이자 최근 GitHub Pages로 기술 블로그를 시작한 67세의 개발자입니다. 정년을 앞두고 평생 해온 연구 내용들을 정리하고 후학들과 공유하고 싶다는 마음으로 블로그를 개설했는데, 처음 며칠은 정말 고생이 많았습니다. 특히 로컬에서는 완벽하게 작동하던 블로그가 GitHub에 푸시하면 자꾸만 빌드 실패 메일이 오는 것이었습니다. 이번 글에서는 제가 겪었던 실제 문제들과 그 해결 과정을 여러분과 공유하겠습니다.

로컬과 GitHub의 환경 차이가 만드는 비극

처음 Jekyll 블로그를 시작할 때 가장 당황했던 부분은 “로컬에서는 잘 되는데 GitHub에 올리면 왜 안 되나?”였습니다. 제 노트북에서는 bundle exec jekyll serve 명령어로 아무 문제 없이 블로그가 실행되었거든요.

원인은 의외로 단순했습니다. GitHub Pages의 서버 환경과 내 로컬 개발 환경의 Ruby 버전, Gem 패키지 버전이 완전히 달랐던 것입니다. 제가 사용하던 Ruby는 3.2.0이었지만, GitHub Pages는 여전히 구식 버전을 사용하고 있었던 거죠.

이 문제를 해결하기 위해 저는 다음과 같은 단계를 거쳤습니다:

1. Gemfile.lock 파일 강제 재생성: rm Gemfile.lock 후 bundle install 실행
2. github-pages gem 명시적 지정: Gemfile에 gem "github-pages", group: :jekyll_plugins 추가
3. Ruby 버전 통일: .ruby-version 파일에 GitHub Pages가 지원하는 버전 명시

특히 세 번째 방법이 가장 효과적이었습니다. GitHub Pages 공식 문서에 나와 있는 권장 Ruby 버전(현재 3.1.4)으로 로컬 환경을 맞추자 더 이상 빌드 에러가 발생하지 않았습니다.

마크다운 문법과 Jekyll의 보이지 않는 충돌

두 번째 문제는 더욱 교활했습니다. 특정 포스트만 빌드가 실패하는 현상이 발생했습니다. 40년간 학술 논문을 작성해온 저로서 마크다운은 충분히 간단하다고 생각했는데, 실은 여러 함정이 있었습니다.

Jekyll은 Liquid 템플릿 엔진을 사용하기 때문에 이중 중괄호()와 같은 특수 문자에 민감합니다. 저는 프로그래밍 예제를 설명할 때 ``처럼 작성했는데, Jekyll은 이것을 자신의 템플릿 문법으로 해석하려다가 에러를 발생시킨 것입니다.

해결 방법은 다음과 같습니다:

• 방법 1: 코드 블록 사용 (권장) ```

{{ variable }}을 사용하세요

- **방법 2**: HTML 엔티티 변환
- `{` → `{`
- `}` → `}`

- **방법 3**: Chirpy 테마의 경우, `_config.yml`에서 특정 확장자 제외 설정

저는 주로 코드 블록을 사용하는 방식을 선택했고, 이 방법이 가장 깔끔하고 가독성이 좋다는 것을 알게 되었습니다.

## GitHub Actions로 빌드 과정 투명하게 들여다보기

문제를 해결하는 과정에서 가장 도움이 된 도구는 **GitHub Actions**였습니다. 이제는 더 이상 이메일로 에러 메시지를 받고 답답해하지 않아도 됩니다.

GitHub 저장소의 "Actions" 탭에 들어가면, 매 푸시 때마다 Jekyll 빌드 과정이 실시간으로 어떻게 진행되는지 볼 수 있습니다. 빨간 X 표시가 나타나면 그 로그를 클릭해서 정확히 어느 줄에서 에러가 발생했는지 확인할 수 있죠.

예를 들어, 저는 한 번은 포스트의 YAML 프론트매터에서 콜론(:)을 제대로 이스케이프하지 않아서 에러가 발생했던 적이 있습니다. 에러 메시지는 이렇게 나왔습니다:

YAML Exception parsing… mapping values are not allowed in this context ```

GitHub Actions 로그를 통해 이것이 _posts/2026-05-05-test.md의 3번째 줄에서 발생했다는 것을 정확히 알 수 있었고, 제목의 콜론 앞에 따옴표를 추가하여 문제를 해결했습니다.

Chirpy 테마 특화 팁

Jekyll의 인기 있는 Chirpy 테마를 사용하면서 알게 된 추가적인 팁들도 있습니다. 이 테마는 매우 우아하고 기능이 풍부하지만, 몇 가지 설정을 놓치면 빌드에 실패할 수 있습니다.

첫째, _config.yml 파일의 url 설정입니다. 저는 처음에 이를 무시했다가 모든 링크가 제대로 작동하지 않아서 깜짝