GitHub Pages에서 한글 폰트가 깨지는 현상, 10년을 헤매다 찾은 해결책

서론: 정년을 앞두고 블로그를 시작하다

올해 67세인 저는 40년간 컴퓨터과학을 가르쳐온 교수입니다. 정년을 앞두고 강의 노트와 연구 경험을 정리할 목적으로 GitHub Pages 블로그를 개설하기로 결심했습니다. 세상이 변했고, 과거처럼 한국 블로그 플랫폼보다는 국제적인 무대에서 지식을 나누고 싶었거든요.

그런데 처음부터 문제가 시작되었습니다. 신나게 첫 포스트를 작성하고 배포했는데, 제 블로그에만 접속하면 한글이 죄다 깨져 보였습니다. 마치 1990년대 웹 초창기로 돌아간 듯한 기분이었죠. “이게 뭐 하는 짓인가” 싶으며 며칠을 헤맸습니다.

GitHub Pages의 한글 인코딩 문제의 원인을 찾다

처음엔 단순히 파일 인코딩 문제라고 생각했습니다. Markdown 파일을 UTF-8로 저장하는 것, 이건 기본 중의 기본이니까요. 하지만 문제는 그렇게 간단하지 않았습니다.

_config.yml 파일의 encoding 설정을 확인했습니다:

encoding: utf-8

이것도 이미 설정되어 있었습니다. 그렇다면 문제는 어디에? 며칠 밤을 샤며 구글링을 했습니다. StackOverflow의 영문 답변들은 대부분 영어권 사용자 입장이었고, 한글의 복잡한 초성·중성·종성 구조를 이해하지 못하는 조언들이었습니다.

대학원생 시절 유닉스 시스템 관리자들과의 경험이 떠올랐습니다. “폰트 문제가 제일 복잡하다”고 늘 말하던 선배들의 조언이 이때 빛을 발했습니다.

Jekyll Chirpy 테마에서 CSS를 직접 수정하다

정답은 CSS의 font-family 설정에 있었습니다.

Jekyll Chirpy 테마는 기본적으로 영문 폰트 위주로 설정되어 있습니다. 제 경우 Noto Sans, Arial, Helvetica 같은 폰트들만 지정되어 있었죠. 한글 폰트를 먼저 우선순위로 두지 않으면, 브라우저는 한글을 렌더링할 때 폴백 폰트를 찾아 헤매다가 결국 시스템 기본 폰트나 깨진 글자로 표시하는 것입니다.

해결책은 다음과 같습니다:

assets/css 디렉토리 안의 style.scss 파일을 찾아 다음과 같이 수정했습니다:

html {
  font-family: 'Noto Sans KR', 'Noto Sans', -apple-system, 
               BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 
               'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 
               'Helvetica Neue', sans-serif;
}

핵심은 ‘Noto Sans KR’을 가장 먼저 배치하는 것입니다. 그 다음에야 영문 폰트들이 와야 합니다.

또한 _sass 디렉토리의 _variables.scss 파일도 수정했습니다:

$font-family-base: 'Noto Sans KR', -apple-system, BlinkMacSystemFont, 
                   'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
$font-family-heading: 'Noto Sans KR', system-ui, -apple-system, sans-serif;

Google Fonts에서 한글 폰트를 적절히 임포트하다

CSS 설정만으로는 부족합니다. 실제 폰트 파일을 어디서 가져올지도 명시해야 합니다.

저는 Google Fonts를 사용하기로 결정했습니다. Noto Sans KR은 유니버설 언어 지원으로 유명하고, 무료이며, 라이선스도 깔끔하기 때문입니다.

_includes/head.html 파일에 다음을 추가했습니다:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@400;700&display=swap" 
      rel="stylesheet">

display=swap 파라미터가 중요합니다. 이것은 폰트 로딩 중에 시스템 폰트를 먼저 표시하고, 폰트가 로드되면 교체하는 FOUT(Flash of Unstyled Text) 전략입니다. 사용자 경험이 훨씬 좋아집니다.

캐시 문제를 해결하고 드디어 성공하다

모든 설정을 마친 후에도 제 블로그에선 여전히 한글이 깨져 보였습니다. 한참을 헤매다가 문제를 찾았습니다: 브라우저 캐시였습니다.

개발자 도구(F12)를 열어 Network 탭을 확인해보니, CSS 파일이 이전 버전 그대로 캐시되어 있었습니다. 저는:

1. 브라우저 캐시를 완전히 삭제했고
2. GitHub Pages의 캐시도 초기화하기 위해 저장소 설정에서 Pages 옵션을 재적용했습니