GitHub Pages에서 Jekyll Chirpy 테마로 블로그를 만들다가 마주친 '빌드 오류의 늪'에서 탈출한 이야기
은퇴 교수가 경험한 GitHub Pages와 Jekyll Chirpy 테마의 빌드 오류 해결 과정
은퇴 후 새로운 도전, GitHub Pages 블로그 시작
2024년 대학을 은퇴하고 한 가지 꿈이 생겼습니다. 평생 강의실에서만 지내온 제가 학문적 경험과 인생 철학을 기록하는 블로그를 만드는 것이었죠. 처음에는 네이버나 티스토리 같은 기존 블로그 플랫폼을 생각했습니다. 하지만 학생 시절 코딩을 했던 경험이 떠올랐고, 마침 주변에서 “GitHub Pages가 정말 멋진데, 특히 Jekyll Chirpy 테마는 기술 블로그에 최고”라고 추천했습니다.
처음에는 단순했습니다. GitHub 계정을 만들고, Jekyll을 설치하고, Chirpy 테마를 다운로드했습니다. 유튜브 튜토리얼을 몇 개 따라하며 “이 정도면 충분하겠네”라고 생각했어요. 하지만 제 천진한 예상과 달리, 실제로 로컬에서 빌드하려는 순간 컴퓨터 화면은 빨간 글씨 오류 메시지로 도배되었습니다. 이것이 제 고난의 시작이었습니다.
Ruby 버전과 Gem 의존성: 처음 만난 ‘진짜’ 오류
첫 번째로 마주친 문제는 “Bundler의 버전이 맞지 않는다”는 오류였습니다. 나이 60대인 저는 처음 느껴보는 절망감을 경험했습니다. 터미널 창에는 “Could not find gem ‘jekyll’ in any of the gem sources listed in your Gemfile”이라는 메시지가 떴고, 저는 당황했습니다.
이 문제를 해결하기 위해 저는 며칠간 인터넷을 뒤졌습니다. 알아낸 것은 다음과 같습니다:
먼저 Ruby의 버전이 중요하다는 것입니다. Chirpy 테마는 특정 Ruby 버전을 요구하는데, 저는 최신 Ruby를 설치했다고 생각했지만, 실제로는 호환되지 않는 버전을 사용하고 있었습니다. 터미널에 ruby --version을 입력해 확인해보니 Ruby 2.7이었고, Chirpy는 Ruby 3.1 이상을 권장했습니다.
그 다음은 Gemfile과 Gemfile.lock의 이해였습니다. 처음에는 이 파일들이 뭐 하는 건지도 몰랐어요. 하지만 점차 알아내면서, 이 파일들이 프로젝트에 필요한 모든 라이브러리(Gem)의 버전을 관리한다는 것을 깨달았습니다. 저는 bundle install 명령어를 실행했고, 이것이 Gemfile에 명시된 모든 의존성을 설치했습니다.
마지막으로 중요한 것은 GitHub Pages가 특정 Jekyll 플러그인만 지원한다는 사실입니다. 제가 처음에는 로컬에서 모든 플러그인을 활성화해서 테스트했는데, GitHub Pages에 푸시했을 때 일부 플러그인이 작동하지 않았습니다. Chirpy 테마 문서를 정독한 후, GitHub Pages에서 안전하게 사용할 수 있는 플러그인만 사용해야 한다는 것을 배웠습니다.
포스트 작성 시 YAML Front Matter: 규칙을 무시하면 안 된다
Ruby 버전 문제를 해결했을 때, 다음 오류는 더욱 교활했습니다. 제 첫 포스트는 로컬에서는 잘 빌드되었는데, GitHub Pages에서는 제목이 제대로 표시되지 않았습니다.
원인은 YAML Front Matter였습니다. Jekyll은 모든 포스트 파일의 맨 앞에 ---로 시작하는 YAML 형식의 메타데이터를 요구합니다. 예를 들어:
1
2
3
4
5
6
---
title: "제목"
date: 2026-05-15 09:00:00 +0900
categories: [카테고리]
tags: [태그1, 태그2]
---
처음에 제가 놓친 부분은 몇 가지였습니다. 첫째, 파일명입니다. Jekyll은 포스트 파일명을 YYYY-MM-DD-제목.md 형식으로 명시적으로 요구합니다. 저는 처음에 파일명을 마음대로 지었다가 포스트가 보이지 않아 황당했습니다.
둘째, 날짜 형식입니다. 시간대(timezone)를 명시해야 하고, 저는 처음에 +0900(한국 표준시)을 빼먹어서 GitHub Pages에서 포스트가 미래 날짜로 인식되어 발표되지 않았습니다.
셋째, 카테고리와 태그의 형식입니다. Chirpy 테마에서는 categories를 배열 형식으로 [도구, 개발] 같이 작성해야 하는데, 저는 초기에 문자열로만 작성했고, 테마가 제대로 작동하지 않았습니다.
이 모든 것을 배우며, 저는 마크다운 작성 시 메타데이터가 얼마나 중요한지 깨달았습니다. 하나의 쉼표나 따옴표가 빠져도 전체 빌드가 실패할 수 있다는 사실은 정말 충격적이었습니다.