GitHub Pages에서 Chirpy 테마로 블로그를 만들었을 때 마주친 예상 밖의 함정들

은퇴 교수의 늦깎이 블로그 도전기

35년을 대학에서 전자공학을 가르친 뒤 작년 정년을 맞았습니다. 여유로운 은퇴 생활을 꿈꾸며 그동안 쌓인 지식과 경험을 정리하는 블로그를 시작하고 싶었습니다. 현역 때 C++과 Java로 프로그래밍을 가르쳤지만, 요즘 세상은 많이 달라져 있었습니다. 아들이 “아빠, 블로그는 GitHub Pages로 만들어야 해. 무료니까”라고 권했고, 저는 호기심으로 시작했습니다.

처음 GitHub Pages와 Jekyll, 그리고 Chirpy 테마를 접했을 때는 “이게 뭐 하는 건가 싶을 정도로 낯설었습니다. 하지만 3개월여 운영하면서 겪은 여러 문제들과 해결책들을 이제 여러분과 공유하고 싶습니다. 제 경험이 혹시 모를 비슷한 상황의 분들께 도움이 될까 해서입니다.

첫 번째 함정: 로컬 개발 환경 설정의 악몽

GitHub에서 Chirpy 테마 저장소를 Fork했을 때, 저는 그게 전부라고 생각했습니다. 하지만 실제로 블로그 글을 작성하고 테스트하려면 로컬 개발 환경을 구성해야 한다는 것을 깨달았죠. Ruby, Jekyll, Bundler 같은 것들을 설치해야 했는데, Windows 10을 사용하던 제 컴퓨터에서는 정말 난관이었습니다.

처음 gem install jekyll bundler 명령어를 입력했을 때는 여러 오류가 났습니다. Ruby의 버전 호환성 문제, DevKit 설치 부재, 그리고 한국 언어 설정으로 인한 인코딩 문제까지… 젊은 시절 어셈블리 디버깅하던 고생이 떠올랐습니다. 결국 WSL2(Windows Subsystem for Linux)를 설치하는 것으로 문제를 해결했습니다.

핵심은 이것입니다: 로컬에서 bundle exec jekyll serve 명령어로 제대로 미리보기를 할 때까지는 GitHub에 푸시하지 마세요. 저는 처음 5번을 GitHub에 잘못 올렸다가 지웠습니다. 각 시도마다 GitHub Pages가 빌드되는 데 2-3분씩 기다려야 했으니 얼마나 답답했는지요.

두 번째 함정: 포스트 작성 규칙의 미묘함

Chirpy 테마에서 블로그 포스트를 작성할 때는 엄격한 규칙이 있습니다. 제 첫 번째 포스트 제목을 “내 첫번째 글입니다”라고 지었을 때, 사이트에 나타나지 않았습니다. 파일명도 2025-05-15-나의첫번째글.md로 작성했는데 반영되지 않는 것입니다.

알고 보니 Jekyll은 파일명에 공백이나 특수문자, 그리고 한글 파일명을 좋아하지 않습니다. 정확한 형식은 YYYY-MM-DD-영문제목.md여야 했습니다. 또한 Front Matter라는 메타데이터 부분도 정확해야 합니다:

---
title: "제목"
date: 2026-05-15 09:00:00 +0900
categories: [카테고리]
tags: [태그1, 태그2]
---

저는 첫 포스트에서 date 형식을 잘못 입력했었습니다. 타임존 설정이 빠져 있었거든요. 이런 작은 실수가 포스트 전체를 숨겨버립니다. 현역 때 학생들의 코딩 실수를 지적할 때는 이렇게 엄격한 규칙을 강조했는데, 제가 자신의 규칙을 지키지 못한 것이 웃기면서도 부끄러웠습니다.

세 번째 함정: 테마 커스터마이징과 의존성 지옥

Chirpy 테마는 기본적으로 아름답지만, 조금만 수정하고 싶으면 복잡해집니다. 제 이름을 더 크게 표시하고 싶어서 _config.yml 파일을 수정하다가 Jekyll이 빌드되지 않는 상황을 겪었습니다. YAML 형식의 들여쓰기가 중요한데, 저는 Tab 키를 사용했고 Jekyll은 Space를 원했던 것입니다.

또한 Chirpy 테마의 여러 플러그인들(jekyll-paginate, jekyll-archives 등)의 버전 호환성 문제도 있습니다. 저는 어려운 마음에 Gemfile을 수정했다가 Bundle 명령어가 실패했습니다. 결국 아들이 “아빠, Gemfile.lock을 건드리지 말고 그냥 기본값을 쓰세요”라고 조언해줬습니다.

제 충고: Chirpy를 처음 사용할 때는 기본 설정을 그대로 유지하세요. 최소 한 달은 기본 상태에서 글 쓰는 데만 집중하십시오. 그 다음에 천천히, 하나씩 커스터마이징하세요. 변경할 때마다 로컬에서 완벽하게 테스트한 후에 GitHub에 올리는 습