GitHub Pages 배포 후 CSS가 안 먹히는 이유, 드디어 알았습니다

은퇴 후 블로깅을 시작하며 겪은 난감한 문제

저는 대학에서 30년을 가르친 후 작년에 은퇴했습니다. 평생 강의노트와 논문으로만 살다가 이제는 그동안 쌓인 경험과 지식을 블로그에 정리하고 싶었습니다. GitHub Pages와 Jekyll을 선택한 것은 무료이면서도 전문적이라고 생각했기 때문입니다. 그런데 로컬에서는 완벽하게 보이던 블로그가 배포 후에는 엉망이었습니다. 스타일시트가 적용되지 않아 흰 배경에 검은 글자만 남았습니다. 처음에는 터미널 명령어를 잘못 입력한 줄 알고 몇 번을 반복했습니다. 하지만 문제는 다른 곳에 있었습니다.

baseurl 설정의 중요성을 깨치다

문제의 원인은 _config.yml 파일의 baseurl 설정이었습니다. 제 리포지토리 이름이 my-blog였는데, GitHub Pages는 사용자 페이지가 아닌 프로젝트 페이지로 배포되었습니다. 사용자 페이지(username.github.io)가 아니면 URL이 username.github.io/my-blog/ 형식이 되는데, Jekyll은 이 경로 구조를 모르고 있었던 것입니다. 로컬에서는 http://localhost:4000에서 실행되므로 상관없지만, 실제 배포 환경에서는 모든 리소스 경로가 잘못되었습니다.

해결책은 간단했습니다. _config.yml에 baseurl: /my-blog를 명시하면 Jekyll은 모든 CSS, JavaScript, 이미지 파일의 경로 앞에 자동으로 /my-blog를 붙여줍니다. CSS 링크가 <link href="/css/style.css">에서 <link href="/my-blog/css/style.css">로 변경되는 것입니다. 이후 배포하니 모든 스타일이 정상 작동했습니다.

개발 환경과 배포 환경의 차이를 이해하기

은퇴 후 프로그래밍을 배운 입장에서 깨달은 중요한 교훈이 있습니다. 개발 환경과 배포 환경은 완전히 다릅니다. 로컬에서 jekyll serve로 실행할 때는 localhost:4000이 루트가 되지만, GitHub Pages에서는 서브디렉토리가 루트가 될 수 있다는 점입니다. 특히 사용자 이름 대신 프로젝트 이름으로 리포지토리를 만들었다면 더욱 주의해야 합니다.

또한 로컬에서 테스트할 때도 정확하게 해야 합니다. 단순히 jekyll serve만으로는 부족하고, baseurl을 포함하여 테스트해야 실제 배포 환경과 동일합니다. 저는 이후로 jekyll serve --baseurl=/my-blog 명령어로 로컬 테스트를 반복했습니다. 이렇게 하면 배포 후 놀라는 일을 피할 수 있습니다.

GitHub Actions로 자동화하면서 배운 점

처음에는 로컬에서 빌드한 후 _site 폴더를 푸시하려 했습니다. 그러나 깃허브 문서를 읽다 보니 이것은 권장되지 않습니다. 대신 GitHub Actions를 설정하여 푸시할 때마다 자동으로 빌드하고 배포하는 것이 표준입니다. 이렇게 하려면 저장소 설정에서 GitHub Pages 소스를 “GitHub Actions”로 선택해야 합니다. 이 과정에서 제 실수가 반복되었지만, Chirpy 테마의 .github/workflows/pages-deploy.yml 파일을 살펴보니 모든 설정이 자동으로 처리되었습니다.

Jekyll은 정적 사이트 생성기이기에 보안 문제도 없고, 속도도 빠릅니다. 개인 블로그부터 소규모 프로젝트 문서까지 활용 범위가 넓습니다. 저도 이제는 블로그를 통해 지난 30년의 강의 경험을 정리하고 있습니다. 여러분도 이러한 배포 환경의 차이를 먼저 이해한다면 시행착오를 줄일 수 있을 것입니다. 이번 포스팅이 도움이 되길 바라며, 댓글로 여러분의 경험담도 나눠주시기를 권장합니다.