GitHub Pages에서 한글 파일명이 자꾸 깨지는 이유, 드디어 알았습니다
20년 경력 개발자가 겪은 GitHub Pages 한글 파일명 인코딩 문제 해결 경험담
은퇴 후 블로그를 시작하며 맞닥뜨린 첫 난제
저는 35년간 대학에서 컴퓨터공학을 가르치다 2년 전 정년퇴임했습니다. 학생들을 가르치던 강의안, 프로젝트 자료, 그리고 수십 년 동안 축적한 개발 경험담들을 정리하고 싶은 욕심이 생겼죠. 그렇게 시작한 것이 Jekyll과 GitHub Pages를 활용한 개인 블로그였습니다.
그런데 첫 포스팅을 작성할 때부터 문제가 터졌습니다. 한글 파일명으로 작성한 마크다운 파일들이 Jekyll 빌드 과정에서 자꾸 깨지는 것이었어요. “데이터베이스-설계-원칙.md” 같은 파일명은 로컬 환경에서는 멀쩡하지만, GitHub에 푸시하고 GitHub Pages에서 렌더링될 때는 문제가 발생했습니다.
처음엔 단순한 오타라고 생각했지만, 같은 현상이 반복되자 이것이 인코딩 문제임을 깨달았습니다. 한국에서 개발했던 시절엔 거의 신경 쓸 일이 없었던 부분인데, GitHub의 글로벌 환경에서는 다르더군요. 이 경험을 통해 배운 것들을 오늘 여러분과 나누고 싶습니다.
Jekyll의 파일명 인코딩 규칙 이해하기
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 설정
_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=”