GitHub Pages에서 Jekyll 블로그가 갑자기 안 보일 때, 나는 이렇게 해결했다

아침 10시, 블로그가 사라졌다

어제까지 멀쩡히 떠 있던 내 Jekyll 블로그가 오늘 아침 갑자기 사라졌다. GitHub Pages에 접속하면 흰 화면만 나타나고, 포스트는 어디론가 증발했다. 나는 컴퓨터 공학 교수로 35년을 근무했지만, 이 순간만큼은 한국 할아버지처럼 “아이고, 뭔가 잘못됐다”는 느낌이 들었다.

처음엔 인터넷 연결 문제인 줄 알았다. 하지만 다른 사이트는 잘 떠있었다. GitHub 저장소에 접속해보니 파일들은 모두 있었다. 문제는 Jekyll이 더 이상 내 마크다운 파일들을 정적 HTML로 변환하지 않고 있었던 것이다. GitHub Pages의 빌드 프로세스가 어디선가 멈춰 있었다.

나는 깊게 숨을 쉬고, 차를 마셨다. 그리고 체계적으로 문제를 진단하기로 결심했다.

GitHub Actions 로그를 살펴보니 진실이 보였다

GitHub Pages의 핵심은 간단해 보이지만, 실제로는 여러 계층으로 이루어져 있다. 저장소에 코드를 푸시하면, GitHub의 백그라운드 서버에서 Jekyll이 자동으로 실행되어 정적 사이트를 생성한다. 이 과정이 실패하면 블로그는 마지막으로 성공한 버전만 보여주거나, 아예 보여주지 않는다.

나는 저장소의 Settings > Pages 탭으로 들어갔다. 거기엔 “Latest deployment” 섹션이 있었고, 빨간 X 마크가 떠 있었다. 매우 불길했다. 더 자세히 보니 “View all deployments”라는 링크가 있었다.

클릭해보니 놀라운 사실이 드러났다. 빌드 로그에는 이렇게 적혀 있었다:

Error: The `_config.yml` file contains invalid YAML syntax.

내가 어제 _config.yml 파일을 수정했을 때, 쉼표나 콜론을 빠뜨렸던 것이다. 마크다운은 관대하지만, YAML은 냉정하다. 한 글자의 실수도 용서하지 않는다.

Chirpy 테마의 _config.yml을 올바르게 수정하는 법

나는 지난해 Chirpy 테마를 적용했다. 반응성 좋고, 다크 모드를 지원하며, 무엇보다 아름다웠다. 하지만 설정 파일이 매우 복잡했다. 내 경험상 Chirpy 사용자들이 가장 자주 빌드 실패를 겪는 이유는 _config.yml 파일을 부정확하게 수정하기 때문이다.

내가 배운 방법을 공유하겠다.

먼저, _config.yml 파일은 절대로 메모장에서 편집하면 안 된다. VS Code나 Sublime Text 같은 제대로 된 텍스트 에디터를 사용해야 한다. 이들은 YAML 문법을 강조 표시해주고, 실수를 줄일 수 있다.

두 번째, Chirpy의 _config.yml에서 자주 틀리는 부분들:

1. URL 설정

url: "https://yourname.github.io"

뒤에 슬래시를 붙이면 안 된다. 이것도 빌드 실패의 원인이 된다.

2. timezone 설정

timezone: Asia/Seoul

따옴표를 붙이지 않아야 한다.

3. social 링크 설정

social:
  - { type: github, link: "https://github.com/yourname" }

대시(-)를 빼먹거나, 중괄호를 빼먹으면 작동하지 않는다.

나는 이번 기회에 전체 파일을 다시 읽으면서 각 항목이 무엇을 하는지 정확히 이해했다. 특히 comments 섹션에서 Disqus를 설정할 때, shortname을 잘못 입력했던 것도 발견했다.

수정을 마친 후, 파일을 저장하고 GitHub에 푸시했다. 그리고 몇 초 뒤, GitHub Actions에서 초록 체크 마크가 떠올랐다. 빌드 성공이다.

YAML 검증 도구를 활용하라

나는 이번 경험 이후로, 절대 실수하지 않기 위해 온라인 YAML 검증 도구를 활용하기로 결심했다. yamllint.com이나 VS Code의 YAML 확장 프로그램을 사용하면, 파일을 저장할 때마다 문법 오류를 실시간으로 확인할 수 있다.

더 나아가, 나는 GitHub 저장소에 로컬 테스트 환경을 구축했다. Ruby를 설치하고, 내 노트북에서 bundle exec jekyll serve 명령어를 실행하면, 푸시하기 전에 문제를 미리 발견할 수 있다. 67세 먹은 내가 터미널 창을 열고 빌드를 테스트하는 모습은 우습지만, 이것만큼 확실한 방법은 없다.

결론: 작은 실수가 모든 것을 멈춘다

교수 생활을 하면서 배운 것이 있다면, 복잡한 시스템일수록 작은 실수가 전체 체계를 마비