저는 35년간 대학에서 컴퓨터공학을 가르치다 2년 전 정년퇴임했습니다. 학생들을 가르치던 강의안, 프로젝트 자료, 그리고 수십 년 동안 축적한 개발 경험담들을 정리하고 싶은 욕심이 생겼죠. 그렇게 시작한 것이 Jekyll과 GitHub Pages를 활용한 개인 블로그였습니다.
그런데 첫 포스팅을 작성할 때부터 문제가 터졌습니다. 한글 파일명으로 작성한 마크다운 파일들이 Jekyll 빌드 과정에서 자꾸 깨지는 것이었어요. “데이터베이스-설계-원칙.md” 같은 파일명은 로컬 환경에서는 멀쩡하지만, GitHub에 푸시하고 GitHub Pages에서 렌더링될 때는 문제가 발생했습니다.
처음엔 단순한 오타라고 생각했지만, 같은 현상이 반복되자 이것이 인코딩 문제임을 깨달았습니다. 한국에서 개발했던 시절엔 거의 신경 쓸 일이 없었던 부분인데, GitHub의 글로벌 환경에서는 다르더군요. 이 경험을 통해 배운 것들을 오늘 여러분과 나누고 싶습니다.
Jekyll은 정적 사이트 생성기로서, 모든 파일명을 UTF-8 인코딩으로 처리합니다. 문제는 여기서 발생합니다. 한글은 멀티바이트 문자이기 때문에, 파일명에 포함되면 GitHub의 서버 환경과 로컬 환경에서 인코딩 처리 방식이 달라질 수 있다는 것이지요.
제가 발견한 것은 GitHub Pages가 실행되는 Linux 서버 환경에서는 파일명의 한글 문자가 때때로 정규화(normalization) 과정을 거친다는 점입니다. 특히 조합된 자모(composed form과 decomposed form)의 차이로 인해 같은 파일이더라도 다르게 인식될 수 있었습니다. 예를 들어 “한글”이라는 단어가 NFD(Normalization Form D) 형태로 변환되면서 파일을 찾지 못하게 되는 것입니다.
처음엔 이 현상을 이해하지 못했습니다. 하지만 여러 GitHub 이슈 포럼을 뒤져본 결과, 이것이 알려진 문제이며 많은 개발자들이 같은 고민을 겪었다는 것을 알 수 있었습니다. 저 역시 수십 년 경력의 개발자였지만, 새로운 환경에서는 겸손하게 배워야 한다는 교훈을 얻었네요.
고민 끝에 저는 다음과 같은 결론에 도달했습니다. Jekyll과 GitHub Pages를 사용할 때는 파일명을 반드시 영문으로 작성해야 한다는 것입니다.
구체적으로 제가 적용한 방법은 이렇습니다:
1
2
3
4
5
6
7
❌ 잘못된 예시:
- 2026-05-15-데이터베이스-최적화-방법.md
- 2026-05-14-파이썬-초급-강좌.md
✅ 올바른 예시:
- 2026-05-15-database-optimization-methods.md
- 2026-05-14-python-beginner-tutorial.md
파일명은 영문으로 하되, YAML 프론트매터의 title 필드에서는 한글 제목을 사용하면 됩니다. 이렇게 하면 GitHub 서버에서도 문제없이 파일을 인식하고, 로컬 빌드 환경과도 완벽하게 일치합니다. 블로그를 방문하는 사용자는 여전히 한글 제목을 보게 되니까요.
저는 이미 작성한 포스트들의 파일명을 모두 영문으로 변경했습니다. 처음엔 번거롭다고 생각했지만, 지금은 이것이 얼마나 현명한 선택이었는지 깨달았습니다. 파일명 변경 후로는 jekyll build 명령어 실행 시 한 번도 경고나 오류가 발생하지 않았으니까요.
_config.yml 파일의 인코딩 설정도 중요합니다. 제 경험상 다음 항목들을 확인하는 것이 좋습니다:
1단계: _config.yml에서 기본 설정 확인 Ruby의 기본 인코딩이 UTF-8로 설정되어 있는지 확인하세요. 저는 다음 한 줄을 _config.yml 상단에 추가했습니다:
1
encoding: utf-8
2단계: Gemfile에서 jekyll-feed 플러그인 확인
RSS 피드 생성 시에도 인코딩이 중요합니다. Gemfile에 gem "jekyll-feed"가 포함되어 있는지, 그리고 최신 버전인지 확인하세요.
3단계: 로컬 빌드 환경 설정 Windows에서 작업하신다면 PowerShell에서 다음 명령어로 인코딩을 UTF-8로 설정할 수 있습니다:
```powershell $env:LANG=”
]]>그날 밤새 문제를 추적하면서 깨달은 것이 있다. Jekyll 블로그의 빌드 실패는 예측 가능하고, 체계적으로 접근하면 충분히 해결할 수 있다는 것이다. 오늘은 내가 경험한 문제들과 해결책을 공유하려고 한다.
처음부터 실수했다. 나는 GitHub Pages의 빌드 실패 알림 이메일을 무심코 지워버렸다. 퇴직 후 이메일이 많아서 대충 훑다가 말이다. 다시 확인하려고 GitHub 저장소 Settings 탭으로 들어갔다.
대부분의 개발자는 이 단계를 건너뛴다. 하지만 이게 핵심이다. GitHub Pages 설정 페이지 하단의 “GitHub Pages” 섹션에서 “Latest deployment” 상태를 꼭 확인해야 한다. 나는 거기서 처음으로 정확한 오류 메시지를 발견했다: “Liquid syntax error: Unknown tag ‘highlight’.”
이 메시지 하나로 내 문제의 30%는 해결됐다. Jekyll은 Liquid 템플릿 엔진을 사용하는데, 어딘가 문법 오류가 있다는 뜻이었다. 나는 최근에 포스트를 수정했던 기억이 났다. 코드 블록을 추가할 때 실수한 게 분명했다.
문제는 거기서 끝나지 않았다. 몇 가지 파일을 수정해도 여전히 빌드가 실패했다. 이번엔 다른 오류였다: “gem dependency error”.
은퇴 전에는 이런 문제를 팀의 주니어 개발자에게 물어봤을 텐데, 이제 나는 혼자다. 로컬 환경에서 bundle install을 실행해봤다. 결과는 예상대로였다. 내 Mac에 설치된 Ruby 버전과 Gemfile에 명시된 버전이 맞지 않았다.
여기서 배운 교훈: GitHub Pages는 특정 버전의 Jekyll과 플러그인만 지원한다. 공식 문서에 따르면 GitHub Pages가 지원하는 의존성 목록이 있다. 나는 처음엔 이걸 몰랐다. 내 로컬 Gemfile.lock을 GitHub의 버전에 맞춰야 했다.
해결책은 간단했다:
1
2
3
source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
이렇게 수정하면, bundle install을 실행할 때 GitHub Pages가 공식 지원하는 정확한 버전들이 설치된다. 내가 원하던 플러그인이 없을 수도 있지만, 적어도 배포는 된다. 이건 타협이 아니라 안정성을 택하는 거다. 30년 경력을 가져도 이런 선택은 항상 맞다.
세 번째 문제는 정말 예상 밖이었다. Chirpy 테마를 사용하다 보니 _config.yml 파일이 매우 복잡했다. 나는 몇 줄을 추가했는데, YAML 형식을 제대로 맞추지 않았다.
YAML은 들여쓰기에 매우 민감하다. Tab 키를 누르면 안 되고 스페이스만 써야 한다. 그리고 보통 2칸이다. 내가 실수한 부분은 리스트 아이템 앞의 대시 다음에 스페이스를 안 넣은 것이었다.
1
2
3
4
5
6
7
8
9
# 잘못된 예
categories:
-도구
-기술
# 올바른 예
categories:
- 도구
- 기술
더 나아가서, 특수문자가 포함된 제목이나 설명을 쓸 때도 문제가 생길 수 있다. 큰 따옴표로 감싸거나 YAML 형식을 정확히 지켜야 한다. 내 블로그에는 한글이 많아서 더욱 주의해야 했다.
문제를 찾는 가장 좋은 방법은 온라인 YAML 검증 도구를 사용하는 것이다. 내가 자주 쓰는 사이트는 yamllint.com이다. _config.yml의 전체 내용을 복사해서 붙여넣으면 오류를 즉시 찾아준다.
이 모든 문제를 빠르게 해결하려면 로컬 환경에서 테스트하는 게 필수다. 나는 처음엔 무시했던 부분인데, 지금은 이게 얼마나 중요한지 안다.
1
bundle exec jekyll serve
이 명령어를 실행하면 로컬 서버(보통 http://localhost:4000)가 떠서 배포 전에 블로그를 미리 볼 수 있다. 만약 이 단
]]>올해로 대학을 떠난 지 5년째입니다. 정년퇴직 후 그동안 쌓인 교육 노하우와 기술 경험을 정리하고 싶어 GitHub Pages에 Jekyll 블로그를 개설했습니다. 첫 포스트를 작성하고 GitHub에 푸시했을 때, 분명 모든 파일이 올바르게 커밋되었는데 웹사이트에는 반영되지 않는 일이 발생했습니다. 그때부터 시작된 나의 기술 탐정 활동이 오늘의 이야기입니다.
처음에는 캐시 문제라고 생각하고 몇 시간을 기다렸습니다. 하지만 여전히 변화가 없었습니다. GitHub 저장소 설정도 확인했고, Jekyll 설정 파일도 여러 번 검토했습니다. 그렇게 하루를 허비한 후, 저는 본격적으로 문제를 진단하기 시작했습니다. 대학에서 40년간 학생들을 가르쳐온 경험이 이때 도움이 되었습니다. 체계적으로 접근하는 것의 중요성 말입니다.
GitHub 저장소의 Actions 탭을 열었을 때, 그 순간 문제를 깨달았습니다. 배포 워크플로우가 실패하고 있었던 것입니다. 빨간 X 표시가 붙은 워크플로우 실행 로그를 들어갔을 때 정확한 오류 메시지가 보였습니다: “GitHub Pages is disabled for this repository.”
이것이 나의 첫 번째 교훈이었습니다. GitHub Pages 기능이 활성화되지 않았던 것입니다. 저장소의 Settings 탭으로 이동해 “Pages” 섹션을 찾았고, 그곳에서 명시적으로 빌드 소스를 설정해야 했습니다. 기본값이 “Deploy from a branch”로 되어 있었는데, 저는 이를 “GitHub Actions”로 변경했습니다.
이 작은 설정 변경이 얼마나 큰 차이를 만드는지 깨달은 순간, 저는 마치 학생들이 복잡한 수식을 단순화했을 때의 그 희열을 느꼈습니다. 많은 초보자들이 이 부분을 놓치고 있다는 것을 알았고, 그것이 바로 제가 이 경험담을 나누려는 이유입니다.
설정을 변경한 후에도 여전히 빌드가 실패했습니다. 이번에는 다른 오류 메시지가 나타났습니다. “Gemfile.lock과 실제 환경의 Ruby 버전이 맞지 않는다”는 내용이었습니다.
Jekyll 블로그를 로컬에서 실행할 때와 GitHub Actions 환경에서의 Ruby 버전이 달랐던 것입니다. 저는 로컬 머신에서 ruby --version으로 확인한 결과를 바탕으로, 같은 버전을 GitHub Actions 워크플로우 파일에서 명시해야 했습니다.
구체적으로는 저장소의 .github/workflows/ 디렉토리에 있는 pages.yml 파일을 수정했습니다:
1
2
3
4
5
6
7
8
9
10
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: '3.2'
bundler-cache: true
이 과정에서 저는 한 가지 중요한 원칙을 다시 한 번 깨달았습니다. 바로 “개발 환경과 배포 환경의 일관성”입니다. 대학 강의실에서 “프로그래밍은 일관성의 예술”이라고 수없이 말했던 나의 말이 정확했다는 것을 실감했습니다.
마지막 문제는 좀 더 교묘했습니다. 빌드는 이제 성공했지만, 배포된 사이트의 스타일이 완전히 깨져 있었습니다. CSS 파일들이 로드되지 않았던 것입니다.
원인은 _config.yml 파일의 baseurl 설정이었습니다. 저는 저장소 이름이 사용자명과 다르기 때문에 baseurl을 올바르게 설정해야 했습니다:
1
2
baseurl: "/repository-name"
url: "https://username.github.io"
만약 사용자 페이지(username.github.io)라면 baseurl을 비워두거나 “/”로 설정하면 되지만, 프로젝트 저장소의 경우 반드시 저장소 이름을 baseurl로 지정해야 합니다.
이 문제를 해결한 후 모든 것이 완벽하게 작동했습니다. 배포 후 약 1-2분이면 웹사이트에 변경 사항이 반영되기 시작했습니다. 그 때의 만족감은 제 인생에서 처음 논문을 게재했을 때의 느낌과 비슷했습니다.
지난 몇 개월간 블로그를 운영하면서, 저는 초기 설정 시 확인해야 할 체크리스트를 만들었습니다:
특히 어느 날 갑자기 블로그 배포가 실패했던 경험이 있는데, 그때의 좌절감과 그 후로 터득하게 된 해결책들을 여러분과 나누고 싶습니다. 제 경험이 혹시 모를 상황에서 여러분의 소중한 시간을 아껴드릴 수 있다면 얼마나 좋을까요.
제 블로그가 처음 빌드 오류를 일으켰을 때는 정말 난감했습니다. 며칠 전까지 멀쩡하던 것이 갑자기 배포가 안 되니까요. GitHub에서 보낸 이메일에는 “Build failed”라고만 적혀 있었고, 구체적인 원인은 전혀 나와 있지 않았습니다.
처음 의심했던 것은 마크다운 파일의 문법 오류였습니다. 교수 시절 습관대로 포스트에 특수 기호를 많이 사용했거든요. 하지만 그것도 문제가 아니었습니다. 며칠을 헤맨 끝에 알게 된 것은 _config.yml 파일의 설정 오류였습니다.
제가 Chirpy 테마를 업데이트하면서 YAML 파일의 들여쓰기가 깨져버린 것이 원인이었습니다. YAML은 들여쓰기를 공백으로만 해야 하는데, 제 에디터가 탭을 섞어서 저장했던 것이죠. 이건 사람의 눈으로는 구분이 거의 불가능합니다. 그래서 저는 이후로 항상 YAML 린터(linter)를 온라인에서 확인하는 습관을 들였습니다.
또 다른 흔한 원인은 gemfile.lock 파일의 충돌입니다. 로컬 환경과 GitHub Actions의 Ruby 버전이 맞지 않으면서 의존성 문제가 생기는 경우가 있습니다. 저는 macOS, Windows, 심지어 Linux 환경에서까지 블로그를 관리해본 적이 있는데, 각각의 환경에서 나타나는 오류가 전부 달랐습니다. 한 번은 M1 맥에서 인텔 맥용 gem을 설치했다가 며칠을 낭비한 적도 있습니다.
Jekyll을 처음 배울 때만 해도 블로그는 정적인 것이라고 생각했습니다. 파일을 올리면 그것으로 끝이라고요. 하지만 현실은 결코 그렇지 않았습니다. 특히 인기 있는 Chirpy 테마는 꽤 자주 업데이트되는데, 매번 업데이트할 때마다 새로운 문제가 생겼습니다.
한 가지 기억에 남는 사건은 Chirpy 버전 5.0으로 업그레이드했을 때입니다. 새로운 기능들이 정말 좋아서 바로 적용했는데, 제 포스트들의 날짜 형식이 모두 깨져버렸습니다. 이전 버전에서는 2026-05-16 형식을 허용했지만, 새 버전에서는 더 엄격한 ISO 8601 형식만 인정했던 것입니다. 150개가 넘는 포스트의 front matter를 모두 수정해야 했습니다.
그 경험 이후로 저는 주요 버전 업그레이드는 항상 테스트 브랜치에서 먼저 해본다는 원칙을 세웠습니다. GitHub의 무료 용량을 활용해서 test 브랜치를 만들고, 거기서 먼저 배포를 시켜본 후 문제가 없으면 main으로 병합하는 방식이죠. 이 방법으로 얼마나 많은 사고를 예방했는지 모릅니다.
또한 Chirpy의 공식 GitHub 저장소를 주기적으로 확인하면서 릴리스 노트(Release Notes)를 꼼꼼히 읽어봅니다. 특히 “Breaking Changes” 섹션은 절대 놓쳐서는 안 됩니다. 사소한 업데이트라고 생각했던 것이 나중에 큰 문제를 일으킬 수 있으니까요.
가장 답답했던 경험은 “로컬에서는 잘 되는데 GitHub Pages에서는 안 되는” 상황입니다. Jekyll을 설치해서 bundle exec jekyll serve 명령으로 로컬 서버를 띄우면 완벽하게 작동하는데, GitHub에 push하면 갑자기 빌드가 실패하곤 했습니다.
원인은 GitHub Actions의 실행 환경이었습니다. 제 로컬 머신에는 Ruby 3.1.2가 설치되어 있었지만, GitHub Actions의 기본 이미지에는 Ruby 3.0.0이 설치되어 있었습니다. 이 버전 차이가 일부 gem
]]>저는 대학에서 30년간 전산학을 가르쳤습니다. 은퇴하면서 혼자만 알고 있던 지식들을 나누고 싶었고, 젊은 시절 막연하게만 생각하던 기술 블로그를 직접 만들어보기로 결심했습니다. 처음엔 WordPress나 Notion을 고려했지만, 결국 선택한 건 GitHub Pages와 Jekyll Chirpy 테마였습니다. 그 결정이 얼마나 현명했는지는 블로그를 운영하면서 점차 드러났습니다.
특히 놀라웠던 부분은 별도의 SEO 플러그인을 설치하지 않았음에도 불구하고, 제 포스트들이 Google 검색 결과에 자연스럽게 노출되기 시작했다는 것입니다. 그제야 깨달았습니다. Jekyll Chirpy가 단순한 테마가 아니라, 현대적인 검색 엔진 최적화 기능들을 이미 탑재하고 있었다는 사실을 말입니다.
처음 Chirpy 테마를 설치했을 때, 제가 가장 먼저 눈에 띈 것은 _config.yml 파일의 구조였습니다. 일반적인 블로그 테마들과 달리 Chirpy는 SEO를 위한 메타데이터 구조가 매우 정교하게 설계되어 있었습니다.
포스트의 Front Matter에 description 필드를 추가하면, 자동으로 메타 디스크립션 태그로 변환됩니다. 이는 Google 검색 결과에서 제목 아래에 나타나는 짧은 설명 문장인데, 클릭률에 매우 큰 영향을 미칩니다. 제가 처음 몇 개 포스트를 작성할 때는 이 필드를 무시했지만, 나중에 추가하니 클릭률이 확연히 올라갔습니다.
또한 Chirpy는 자동으로 Open Graph 메타 태그를 생성합니다. 이것이 무엇이냐면, 제 포스트를 Twitter나 Facebook 같은 소셜 미디어에 공유할 때 썸네일 이미지와 설명이 함께 나타나는 기능입니다. 이 기능 덕분에 소셜 미디어에서의 공유율도 자연스럽게 증가했습니다.
GitHub Pages에 처음 블로그를 배포했을 때, 저는 얼마나 많은 기술적 세부사항들이 자동으로 처리되고 있는지 몰랐습니다. Chirpy 테마는 기본적으로 sitemap.xml 파일을 자동으로 생성해줍니다. 이 파일은 검색 엔진의 크롤러 봇이 제 블로그의 모든 페이지를 효율적으로 발견하고 인덱싱할 수 있도록 돕습니다.
저는 은퇴 후 처음으로 Google Search Console에 제 블로그를 등록했습니다. 그 과정에서 이미 생성된 sitemap.xml을 Google에 제출했고, 놀랍게도 며칠 내에 제 페이지들이 Google의 인덱스에 추가되기 시작했습니다. 이는 WordPress에서 별도의 플러그인을 통해 수작업으로 설정해야 하는 것과는 완전히 다른 경험이었습니다.
robots.txt 파일도 마찬가지입니다. 이 파일은 검색 로봇들에게 어떤 페이지를 크롤링할 수 있고 어떤 페이지는 피해야 하는지를 알려줍니다. Chirpy는 이를 자동으로 생성하며, 기본 설정도 매우 합리적입니다.
저는 대학 강의 경력을 바탕으로 “C언어 포인터 개념 완벽 이해하기”라는 제목의 포스트를 작성했습니다. 내용은 제 수십 년의 강의 경험과 학생들이 가장 많이 범하는 실수들을 담았습니다. 포스트를 배포한 지 정확히 2주 후, 제가 확인한 것은 놀라운 일이었습니다.
“포인터 개념 쉽게 배우기”라는 검색어로 Google 검색을 했을 때 제 포스트가 3페이지에 나타났습니다. 아무런 백링크 전략도 없이, 단지 Chirpy 테마가 자동으로 처리해준 SEO 기능만으로 말입니다. 3개월 후에는 1페이지로 올라갔고, 현재는 해당 키워드의 상위 5개 결과에 포함되어 있습니다.
이런 성과가 가능했던 이유를 분석해보니, 몇 가지 핵심 요소가 작용했습니다. 첫째, Chirpy 테마가 자동으로 생성하는 구조화된 데이터(Schema.org 마크업)가 검색 엔진이 콘텐츠를 더 잘 이해하도록 도왔고, 둘째, 모바일 친화적인 반응형 디자인이 Google의 모바일 우선 인덱싱 정책과 완벽하게 부합했으며, 셋째, 빠른
]]>대학을 정년퇴직한 지 어느덧 2년이 되었습니다. 40년간 정보통신학을 가르쳤던 저는 퇴직 후 한 가지 꿈을 품었는데, 바로 그간의 노하우와 경험을 온라인으로 공유하는 것이었습니다. 그래서 선택한 것이 Jekyll과 GitHub Pages였습니다. 무료이고, 깔끔하며, 기술적으로도 흥미로웠거든요.
처음 몇 주는 정말 즐거웠습니다. Chirpy 테마를 다운로드받고, 로컬에서 번들을 설치하고, 첫 번째 포스트를 작성했을 때의 그 희열은 지금도 생생합니다. 그런데 말입니다. GitHub에 push한 지 5분 후, 이메일이 하나 날아왔습니다.
“The page build failed.”
그 메시지를 받는 순간, 제 얼굴은 확 굳어져 버렸습니다.
처음엔 원인을 찾기가 정말 어려웠습니다. GitHub에서 제공하는 에러 메시지는 너무 일반적이었거든요. “There was an error building your site.” 이것뿐이었습니다. 마치 의사가 환자에게 “당신은 아픕니다”라고만 하는 것 같은 답답함이었어요.
저는 처음에 Jekyll의 공식 문서를 읽었습니다. 그러다가 문제를 발견했습니다. 바로 Ruby 버전의 호환성 문제였습니다. 제 로컬 머신에는 Ruby 3.2가 설치되어 있었는데, GitHub Pages가 사용하는 Jekyll은 특정 버전의 gem에만 호환되었던 것입니다.
두 번째 문제는 플러그인이었습니다. 저는 흥미로워서 여러 플러그인을 _config.yml에 추가했는데, GitHub Pages가 공식적으로 지원하지 않는 플러그인들이 섞여 있었습니다. Jekyll은 로컬에서는 잘 작동하지만, GitHub Pages의 safe mode에서는 특정 플러그인만 실행되기 때문입니다.
세 번째는 인코딩 문제였습니다. 저는 한글로 된 마크다운 파일 이름을 사용했는데, 이것이 빌드 과정에서 문제를 야기했습니다. Windows 환경에서 작업했던 터라 더욱 그랬던 것 같습니다.
이 문제들을 해결하는 데는 약 3주가 걸렸습니다. 제 해결 과정을 여러분과 공유하겠습니다.
먼저 가장 중요한 것은 GitHub Pages 설정을 확인하는 것입니다. 저는 저장소의 Settings > Pages로 가서, 어떤 브랜치를 사용하고 있는지, 빌드 소스가 무엇인지를 다시 확인했습니다. 현재 GitHub Pages는 GitHub Actions를 기본으로 사용하고 있으므로, 워크플로우 파일도 확인해야 합니다.
두 번째는 로컬 빌드 환경을 GitHub와 동일하게 맞추기였습니다. Gemfile을 열어서 github-pages gem을 추가했습니다.
1
gem "github-pages", group: :jekyll_plugins
그리고 bundle install을 실행했습니다. 이렇게 하면 로컬에서도 GitHub와 동일한 버전의 gem들이 설치됩니다.
세 번째는 _config.yml을 꼼꼼히 검토했습니다. Chirpy 테마에서 제공하는 기본 설정에서 제가 추가한 부분들을 하나하나 제거해가며 테스트했습니다. 그 결과, jekyll-spaceship 플러그인이 문제였다는 것을 발견했습니다. 이 플러그인은 GitHub Pages의 safe mode에서 지원하지 않았기 때문입니다.
네 번째는 파일 이름 규칙을 준수하는 것이었습니다. 포스트 파일은 반드시 YYYY-MM-DD-title.md 형식으로 작성해야 하며, 제목에 한글을 피하는 것이 좋습니다. 카테고리나 태그는 한글로 지정할 수 있지만, 파일 이름은 영문으로 해야 합니다.
다섯 번째는 GitHub Actions 워크플로우를 확인하는 것입니다. Chirpy 테마를 사용한다면, .github/workflows 디렉토리에 자동으로 생성되는 워크플로우 파일을 살펴봐야 합니다. 저는 이 파일에서 Jekyll 버전과 Ruby 버전을 명시적으로 지정했습니다.
마지막으로, 저는 로컬에서 bundle exec jekyll serve로 테스트한 후에만 GitHub에 push하기로 결정했습니다. 이렇게 하면 로컬에서 실제 빌드 환경과 동일한 조건에서 테스트할 수 있습니다.
40년간 학생들을 가르치면서 배운 것 중 하나가 있습니다. 그것은 “작은 것부터 차근차근 확인하라”는 것입니다. 복잡한 문제라도 결국은 작은
]]>제가 은퇴 후 취미로 기술 블로그를 시작한 지 어느덧 3년째입니다. 정년퇴직 후 한가로운 시간을 보내려다가 옛 개발자의 본능으로 다시 손에 들게 된 것이 바로 이 GitHub Pages와 Jekyll이었죠. 처음엔 Chirpy 테마를 적용해서 매주 기술 팁을 올리는 것이 얼마나 즐거웠는지 모릅니다.
그런데 어느 날 갑자기 일이 터졌습니다. 평소처럼 마크다운 파일을 작성하고 커밋했는데, GitHub Actions에서 “Build failed” 메시지가 떴던 겁니다. 젊은 시절 같았으면 몇 분 만에 해결했을 문제일 텐데, 한 30분을 헤맸거든요. 그 경험을 오늘 여러분과 나누고 싶습니다.
처음 마주친 빌드 실패의 원인은 정말 황당했습니다. 바로 포스트의 YAML 프론트매터(Front Matter) 부분에서 날짜 형식이 잘못되었다는 것이었죠.
Jekyll은 매우 까다로운 문법 검사자입니다. 특히 포스트 파일의 맨 앞에 오는 YAML 설정 부분에선 더더욱 그렇습니다. 저는 처음에 다음과 같이 작성했었습니다:
1
2
3
4
---
title: "제 블로그 첫 포스트"
date: 2026-05-16 9:00:00 +0900
---
문제가 보이시나요? 9:00:00 부분입니다. Jekyll은 숫자 앞에 0을 붙여서 09:00:00으로 써야 한다고 요구합니다. 이것은 ISO 8601 표준 날짜 시간 형식을 따르기 때문인데, 저처럼 오십 몇 년 만에 코딩을 다시 시작한 사람에겐 이런 세부사항이 정말 함정처럼 느껴졌습니다.
Chirpy 테마를 사용할 때는 특히 이 부분이 중요합니다. GitHub Pages가 자동으로 생성하는 _site 폴더의 구조가 이 날짜 형식에 따라 결정되거든요. 날짜가 파싱되지 않으면 전체 사이트 구조가 깨져버립니다.
두 번째 배운 점은 에러 메시지를 제대로 읽는 것의 중요성입니다. 처음엔 GitHub 저장소의 “Actions” 탭에서 빨간 X 표시만 보고 좌절했는데, 사실 그 안에 매우 상세한 로그가 남아있었습니다.
저는 이렇게 확인했습니다:
처음엔 그냥 “Build failed”라는 메시지만 봤는데, 로그 전체를 읽으니 실제로는 “Liquid Exception” 같은 구체적인 오류가 있었습니다. 예를 들어 제 경우엔:
1
Liquid Exception: Undefined variable: site.title in _layouts/post.html
이런 식의 메시지가 있었는데, 이것은 제가 _config.yml 파일에서 title 값을 제대로 설정하지 않았다는 뜻이었습니다. 젊은 시절 디버깅 경험이 있었기에 이 정도는 쉽게 해결할 수 있었지만, 아무튼 로그를 읽는 것이 얼마나 중요한지 깨달았습니다.
그 이후로 저는 더 이상 GitHub에 바로 푸시하지 않습니다. 항상 로컬 환경에서 먼저 빌드를 테스트합니다. 은퇴 전에 배웠던 “테스트 주도 개발”이 여기서 다시 빛을 발하네요.
로컬에서 Jekyll을 실행하려면:
1
bundle exec jekyll serve
이 명령어 하나면 됩니다. 그러면 localhost:4000에서 실시간으로 블로그를 미리 볼 수 있고, 만약 오류가 있다면 터미널에서 즉시 확인할 수 있습니다. 이렇게 하면 마크다운 문법, YAML 설정, CSS 문제 등을 모두 로컬에서 해결한 후 푸시할 수 있습니다.
처음엔 이 과정이 번거롭다고 생각했지만, 이제는 이것이 빌드 실패를 90% 이상 방지해주는 보험이라는 것을 알게 되었습니다. 특히 Chirpy 같은 복잡한 테마를 사용할 때는 더욱 그렇습니다.
또 다른 흔한 원인은 Gemfile.lock 파일의 버전 불일치입니다. GitHub Pages가 업데이트되면서 Jekyll이나 플러그인의 버전도 변할 수 있는데, 제 로컬 환경과 GitHub 서버의 버전이 다르면 빌드 결과가 달라질 수
저는 30년을 대학에서 전자공학을 가르쳤습니다. 작년 은퇴 후, 평생 정리해온 강의 노트와 연구 자료를 온라인에 공개하고 싶었습니다. 어렸을 때부터 좋아하던 글쓰기도 다시 시작하고 싶었죠. 그렇게 시작한 것이 Jekyll Chirpy 블로그였습니다.
처음 블로그를 만들고 GitHub에 올렸을 때, 저는 자동 배포가 되어야 한다고 생각했습니다. “GitHub Pages는 자동으로 처리해주겠지”라는 막연한 신뢰가 있었거든요. 그러나 현실은 냉혹했습니다. 며칠을 기다려도 블로그가 업데이트되지 않는 것이었습니다. 마치 제 강의 자료가 검은 구멍으로 빨려 들어가는 것 같았습니다.
아무리 커밋을 해도 변화가 없자, 저는 체계적으로 접근하기로 했습니다. 학생들을 가르칠 때 항상 “문제를 정확히 파악하고 가설을 세워라”고 했으니까요.
먼저 확인한 것은 GitHub 저장소의 Settings입니다. GitHub Pages가 제대로 활성화되었는지, 어느 브랜치에서 배포되고 있는지를 살폈습니다. 제 경우 문제가 바로 드러났습니다. Build and deployment 섹션에서 “Deploy from a branch”가 선택되어 있었지만, 실제로 Jekyll 빌드 프로세스가 실행되지 않고 있었던 것입니다.
GitHub Pages에서 제공하는 자동 Jekyll 빌드는 일정한 조건을 만족해야 합니다. 특히 저는 Chirpy 테마를 사용했는데, 이것이 기본 Jekyll 테마가 아니라서 자동 빌드가 작동하지 않았던 것이죠.
문제를 파악한 후, 해결책은 명확했습니다. GitHub Actions를 사용하여 직접 빌드 파이프라인을 구축하는 것이었습니다.
GitHub Actions는 GitHub에서 제공하는 자동화 서비스입니다. 저는 처음에 이것을 “복잡한 개발자용 도구”라고 생각했습니다만, 실제로는 상당히 직관적이었습니다. Jekyll 블로그 빌드를 위한 표준 워크플로우가 이미 많이 공개되어 있었거든요.
저는 .github/workflows/ 디렉토리에 build.yml 파일을 생성했습니다. 이 파일에는 다음과 같은 내용이 포함되어 있습니다:
이렇게 설정하면, 제가 마크다운 파일을 작성해서 GitHub에 푸시하는 순간, 자동으로 전체 프로세스가 시작됩니다. 마치 제 강의실 안의 조수들이 자동으로 수업 자료를 정리하고 게시판에 붙여주는 것처럼요.
첫 번째 빌드는 성공했지만, 모든 것이 완벽하지는 않았습니다. 몇 가지 추가 설정이 필요했습니다.
첫째, GitHub Token 권한 문제입니다. GitHub Actions가 gh-pages 브랜치에 쓰기 권한을 가져야 합니다. 저는 Repository Settings에서 “Workflow permissions”를 “Read and write permissions”로 설정했습니다.
둘째, 루비 버전 호환성입니다. Chirpy 테마는 특정 루비 버전과 특정 gem 버전을 요구합니다. 저는 Gemfile을 정확히 구성하고, 로컬에서 bundle exec jekyll serve로 테스트한 후에야 GitHub에 올렸습니다. 이것이 많은 시간을 절약해주었습니다.
셋째, 배포 설정입니다. GitHub Pages Settings에서 “Build and deployment” 섹션의 Source를 “GitHub Actions”로 변경했습니다. 이것이 가장 중요한 부분이었습니다.
이 모든 과정을 거치면서, 저는 몇 가지 중요한 교훈을 얻었습니다.
첫째, 문서를 읽는 것의 중요성입니다. GitHub Pages 공식 문서에는 모든 해답이 있었습니다. 저는 너무 빨리 가정하고 넘어갔습니다.
둘째, 로컬에서의 테스트입니다. GitHub에 바로 올리기 전에 로컬 머신에서 완벽하게 작동하는지 확인하는 것이 얼마나 중요한지 깨달았습니다. 이것이 개발 시간을 절반으로 단축했습니다.
셋째, 커뮤니티의 힘입니다. GitHub의
]]>대학에서 정년퇴직한 지 2년이 지났습니다. 50년 가까운 프로그래밍 경력을 정리하고 싶다는 생각에 GitHub Pages로 블로그를 시작했죠. 요즘 유행한다는 Jekyll Chirpy 테마를 사용하기로 결정했고, 처음엔 잘 진행되는 것처럼 보였습니다.
그런데 문제가 생겼습니다. 로컬 환경에서 bundle exec jekyll serve를 입력하면 빌드가 되는데, GitHub에 푸시하면 빌드 오류 메일이 날아오는 것입니다. 처음엔 이것이 단순한 실수라고 생각했지만, 10번 이상 시도해도 같은 오류가 반복되었습니다. 결국 며칠을 헤매다 근본적인 원인을 찾게 되었고, 그 경험을 여러분과 나누고 싶습니다.
내가 겪던 주요 증상은 이랬습니다. 로컬에선 모든 게 완벽했습니다. 마크다운 파일을 작성하고, bundle exec jekyll serve를 실행하면 http://localhost:4000에서 블로그가 멋지게 렌더링되었거든요. 그런데 git push를 하면 GitHub Actions에서 자동 빌드가 실패하는 메시지가 떴습니다.
오류 메시지를 자세히 살펴보니 문제가 명확했습니다. 로컬 환경의 Jekyll 버전과 GitHub Pages가 사용하는 버전이 달랐던 것입니다. 나는 로컬에서 최신 버전의 Jekyll(4.3.x)을 사용하고 있었는데, GitHub Pages의 기본 환경은 여전히 이전 버전을 기반으로 하고 있었던 거죠.
특히 Chirpy 테마는 최신 기능들을 적극 활용하기 때문에, 버전 호환성이 매우 중요합니다. 예를 들어 새로운 플러그인이나 액체 필터(Liquid Filter) 같은 기능들은 구 버전에서 지원되지 않습니다. 나는 로컬에서 테스트했을 때 이런 기능들이 모두 정상 작동했기 때문에, 원격 저장소에서도 당연히 작동할 거라고 착각했던 것입니다.
문제를 해결하기 위해 처음 한 일은 Gemfile을 정확히 설정하는 것이었습니다. Chirpy 테마의 공식 저장소에서 제공하는 Gemfile을 다시 확인했습니다.
1
2
3
4
5
6
7
8
9
source "https://rubygems.org"
gem "jekyll", "~> 4.3"
gem "jekyll-paginate", "~> 2.0"
gem "jekyll-redirect-from"
gem "jekyll-seo-tag"
gem "jekyll-archives"
gem "jekyll-sitemap"
gem "jekyll-relative-links"
중요한 것은 버전을 명시하는 방식입니다. ~>는 “호환성이 있는 버전을 사용하라”는 뜻인데, 이를 통해 로컬과 GitHub Pages 환경 모두에서 비슷한 버전의 gem을 사용하도록 강제할 수 있습니다.
또한 bundle update를 정기적으로 실행하되, 그 결과인 Gemfile.lock을 반드시 커밋해야 합니다. 이 파일이 있으면 GitHub에서도 정확히 같은 버전을 설치하게 됩니다. 내가 처음에는 .gitignore에서 실수로 이 파일을 제외했었는데, 이것이 원인 중 하나였습니다.
GitHub Pages는 이제 GitHub Actions를 통해 자동으로 빌드됩니다. Chirpy 테마를 사용한다면 .github/workflows/ 디렉토리에 빌드 설정 파일이 있을 것입니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
name: Build and Deploy
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Ruby
uses: ruby/setup-ruby@v1
with:
ruby-version: 3.2
bundler-cache: true
- name: Build
run: bundle exec jekyll build
나는 이 설정에서 Ruby 버전도 명시적으로 설정했습니다. 로컬에서 ruby -v로 확인한 버전과 GitHub Actions에서 사용하는 버전을 맞추는 것이 중요합니다. 만약 로컬에서 Ruby 3.1을 사용하는데 GitHub에서 3.0을 사용한다면, 호환성 문제가 발생할 수 있습니다.
또한 bundler-cache: true는 매우 중요한 설정입니다. 이것이 Gemfile.lock을 읽고 정확한 버전들을 캐시하기 때문입니다.
가장 근본적인 해결책은 로컬 환경을 GitHub Pages와 동일하게 만드는 것입니다. GitHub Pages 공식 문서에 따르면, 로컬에서 다음 명령어를 실행해야 합니다:
1
bundle add github-pages
이 gem을 추가하면 로컬 환경이 자동으로 GitHub Pages의
]]>작년 가을, 저는 대학을 떠나기 전에 40년간 쌓아온 개발 경험을 정리하고 싶었습니다. 후학들을 위해 실전 경험담을 남기려는 욕심이었죠. “GitHub Pages와 Jekyll로 무료 블로그를 만들어야겠다”는 생각에 설렜던 그 날이 지금도 생생합니다.
그런데 예상과 달랐습니다. 처음 로컬 환경에서 Jekyll을 돌렸을 때 화면에 아무것도 뜨지 않았던 것입니다. 40년 경력도 무색했습니다. 2시간 동안 헤맸던 기억, 오늘 그 경험을 여러분과 나누고 싶습니다.
당시 저는 Chirpy 테마를 선택했는데, bundle install 후 bundle exec jekyll serve를 입력했을 때 이런 메시지를 봤습니다:
1
2
3
4
5
6
7
8
Configuration file: /Users/professor/blog/_config.yml
Source: /Users/professor/blog
Destination: /Users/professor/blog/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.432 seconds.
Auto-regeneration: enabled for '/Users/professor/blog'
Server address: http://127.0.0.1:4000
“잘 됐네?” 싶어서 브라우저를 열었습니다. 그런데 로드되는 내용이 기대와 달랐습니다. CSS가 전혀 적용되지 않았고, 이미지도 깨졌습니다. 마치 1990년대 웹사이트를 보는 듯했습니다.
대학 시절 처음 배운 프로그래밍이 생각났습니다. “문제를 체계적으로 파악하라”던 교수님 말씀. 저는 개발자 도구(F12)를 열었고, 콘솔 탭을 확인했습니다. 그곳에는 404 에러가 떠있었습니다. 정적 자산(CSS, JS, 이미지)을 찾지 못한 것이었습니다.
baseurl 설정의 함정이틀을 고민한 끝에, 저는 _config.yml 파일을 다시 읽어보기로 결심했습니다. 경험상 설정 파일에 답이 있었거든요.
1
2
baseurl: ""
url: "https://yourusername.github.io"
이 두 줄이 문제였습니다. GitHub Pages의 저장소 이름이 yourusername.github.io가 아닌 경우, baseurl을 반드시 설정해야 한다는 것을 놓쳤던 것입니다.
예를 들어, 제 저장소 이름이 my-blog라면:
1
2
baseurl: "/my-blog"
url: "https://yourusername.github.io"
이렇게 수정해야 했습니다. 로컬 테스트를 위해서는:
1
bundle exec jekyll serve --baseurl "/my-blog"
이 명령어를 사용해야 했던 것입니다. 간단하지만 치명적인 실수였습니다.
문제를 해결한 후, 저는 같은 실수를 반복하지 않기 위해 몇 가지를 정리했습니다.
첫째, 로컬 환경과 배포 환경의 차이를 명확히 하기.
로컬에서 완벽하게 보여도 GitHub Pages에 올렸을 때 깨질 수 있습니다. 저는 배포 전에 항상 이 명령어로 테스트했습니다:
1
JEKYLL_ENV=production bundle exec jekyll build
둘째, Gemfile 관리의 중요성 인식.
버전 충돌은 개발자의 영원한 숙제입니다. 저는 팀 동료나 다른 환경에서도 동일하게 작동하도록 Gemfile.lock을 항상 커밋했습니다:
1
2
git add Gemfile Gemfile.lock
git commit -m "Update dependencies"
셋째, .gitignore 설정 확인.
Jekyll은 _site 폴더, .jekyll-cache 폴더 등을 생성합니다. 이들은 GitHub에 올리면 안 됩니다. Chirpy 테마를 사용하면 기본으로 설정되어 있지만, 저는 항상 확인했습니다.
그 오류를 해결한 이후, 저는 벌써 150개의 포스팅을 작성했습니다. 프로그래밍 언어별 팁, 알고리즘 문제 풀이, 그리고 인생 경험담 등.
무엇보다 기쁜 것은, 이 블로그를 통해 세계 각지의 학생들과 교류하게 되었다는 것입니다. 시간대가 다른 곳에서 온 질문들에 답하며, 저는 여전히 배우고 있습니다.
지금 생각해보니, 그 2시간의 좌절은 값진 투자였습니다. 기술 문제해결의 본질을 다시 한 번 깨달았기 때문입니다.
혹시 Jekyll이나 GitHub Pages로 블로그를 시작하려고 하시나요? 이 글이 도움이 되었다면, 댓글로 당신의 경험을 나눠주세요. 어떤 오류를 만났고, 어떻게 해결했는지 말이죠. 우리 모두가 함께 배우는 커뮤니티가 되었으면 좋겠습니다. 그리고 이 포스트가 도움이 되었다면 GitHub에서 제 블로그 저장소에 star를 눌러주시면 큰 격려가 될 것입니다.
]]>