GitHub Pages 배포 후 CSS가 안 먹힐 때, 나는 이렇게 해결했다

은퇴 후 취미로 시작한 기술 블로그

대학에서 30년을 가르친 후 올해 초 은퇴했습니다. 평생을 학생들 앞에서만 살다가 갑자기 자유시간이 생기니, 몇십 년 전부터 알고 있던 기술들을 정리해서 공유하고 싶었습니다. 마침 요즘 개발자들이 GitHub Pages로 블로그를 많이 만든다기에, 저도 배워보자는 마음으로 시작했습니다.

처음엔 순탄했습니다. GitHub에 레포지토리를 만들고, Jekyll의 Chirpy 테마를 설치하고, 로컬에서 bundle exec jekyll serve 명령어를 실행하면 멋진 블로그가 웹 브라우저에 떴습니다. “아, 이렇게 간단한가?” 하며 첫 포스트를 작성했고, GitHub에 push했습니다. 그런데…

CSS 파일이 로드되지 않은 황당한 상황

GitHub에 업로드한 후 블로그 URL에 접속했을 때의 충격은 잊을 수 없습니다. 로컬에서는 깔끔하던 레이아웃이 완전히 망가져 있었던 것입니다. 헤더도 없고, 사이드바도 없고, 텍스트만 덩그러니 떠있었습니다.

개발자 도구(F12)를 켜서 Network 탭을 보니, CSS 파일들이 404 에러로 로드되지 않고 있었습니다. assets/css/style.css 같은 파일들 말입니다. 로컬에서는 잘 돌아가는데, 왜 배포된 사이트에서만 문제가 생기는 걸까요? 이 문제로 저는 하루종일 구글링을 하며 시간을 낭비했습니다.

문제는 바로 _config.yml 파일의 baseurl 설정에 있었습니다. GitHub Pages를 사용할 때, 만약 당신의 레포지토리 이름이 username.github.io가 아닌 다른 이름이라면(예: my-blog), Jekyll은 루트 경로가 아닌 /my-blog/ 경로에 배포됩니다. 하지만 이 설정을 제대로 하지 않으면, Jekyll은 여전히 루트 경로를 기준으로 CSS 파일의 경로를 생성하게 되는 것이죠.

해결책: baseurl과 url 설정의 정확한 이해

결국 찾아낸 해결책은 간단했습니다. _config.yml 파일을 다음과 같이 수정하면 됩니다:

url: "https://yourusername.github.io"
baseurl: "/my-blog"  # 레포지토리 이름 (username.github.io라면 빈 값)

만약 당신의 GitHub Pages 주소가 yourusername.github.io라면, baseurl은 비워두면 됩니다. 하지만 yourusername.github.io/my-blog 형태라면, baseurl을 /my-blog로 설정해야 합니다. 이렇게 설정하면 Jekyll이 빌드할 때 모든 CSS, 이미지, 자바스크립트 파일의 경로 앞에 자동으로 baseurl을 붙여줍니다.

제 경우엔 레포지토리 이름이 teacher-tech-blog였는데, 이 설정 후 모든 게 깔끔하게 정렬되었습니다. 헤더도 나타났고, 사이드바도 제 위치에 앉았으며, 포스트들도 제대로 스타일이 적용되었습니다. 그때의 희열이란!

로컬에서 테스트할 때도 baseurl을 고려하자

다만 한 가지 더 배운 점이 있습니다. 이렇게 baseurl을 설정한 후에는 로컬에서 테스트할 때도 신경을 써야 합니다. 로컬에서 bundle exec jekyll serve를 실행할 때는 http://localhost:4000/teacher-tech-blog/로 접속해야 실제 배포 환경과 동일한 경험을 하게 됩니다. 만약 그냥 http://localhost:4000/에 접속하면, CSS가 제대로 로드되지 않는 것처럼 보입니다.

더 편하게 하려면, 개발할 때는 baseurl을 빈 값으로 설정해서 테스트하고, 배포 전에만 실제 값으로 변경하는 방법도 있습니다. 또는 Jekyll 실행 시에 옵션으로 --baseurl "" 같이 전달할 수도 있습니다.

Chirpy 테마 특화 팁

Jekyll의 Chirpy 테마를 사용한다면 추가로 알아두면 좋은 점들이 있습니다. Chirpy는 매우 잘 만들어진 테마라서, 설정만 제대로 하면 대부분의 문제가 해결됩니다.

_config.yml에서 lang, timezone, title, description, social 등의 항목들을 꼼꼼히 설정하는 것이 중요합니다. 특히 social 섹션에 GitHub, Twitter, LinkedIn 등의 링크를 추가하면, 사이드바에 자동으로 아이콘이 나타납니다.

또한 포스트를 작성할 때는 YAML front matter를 정확하게 입력해야 합니다. title, date, categories, tags, description 등이 제대로 입력되어야 검색 엔진 최적화(SEO)도 잘되고, 블로그의 메타데이터도 깔끔하게 관리됩니다.

은퇴자의 깨달음

이 경험을 통해 저는 한 가지를 깨달았습니다. 기술은 늘 문제를 안고 있지만, 그 문제를 해결하는 과정 자체가 학습이라는 점입니다. 학교에서 학생들을 가르칠 때도 “답을 알려주기보다는 문제를 풀어가는 과정을 배우게 하라”고 늘 강조했는데, 은퇴 후에도 그 원칙이 여전히 유효했습니다.

GitHub Pages의 baseurl 문제는 매우 흔한 문제지만, 많은 초보자들이 겪고도 오래 해결하지 못합니다. 공식 문서에 명확하게 설명되어 있지 않거나, 설명이 너무 기술적이기 때문입니다. 하지만 한번 겪고 나면, 그 이후로는 블로그를 운영할 때 이런 종류의 경로 문제를 쉽게 진단할 수 있게 됩니다.

혹시 당신도 GitHub Pages에 블로그를 배포했는데 CSS가 안 먹혀서 고민하고 있다면, 오늘 제 경험담이 도움이 되길 바랍니다. 간단한 설정 하나가 얼마나 큰 차이를 만드는지, 그리고 문제 해결의 즐거움이 무엇인지 직접 경험해 보세요. 그리고 혹시 다른 방법으로 이 문제를 해결한 경험이 있다면, 댓글로 공유해 주시기 바랍니다!