GitHub Pages에서 한글 폰트가 깨지는 현상, 67세 교수의 5년 고민을 끝낸 해결법
Jekyll Chirpy 블로그에서 한글 폰트가 제대로 표시되지 않는 문제를 완벽하게 해결하는 방법
나의 5년 묵혀있던 숙제
은퇴 후 개인 기술 블로그를 시작한 지 어느덧 5년이 되었습니다. 컴퓨터과학과 교수로 30년을 지낸 저는 정년 이후에도 기술 지식을 나누고 싶었거든요. GitHub Pages와 Jekyll을 선택했고, 멋진 Chirpy 테마까지 입혔습니다. 그런데 말입니다.
처음 몇 개월은 정말 짜증스러운 문제가 있었습니다. 제 포스트에는 분명히 한글이 가득했는데, 실제 블로그에 접속해보면 어딘가 이상했던 것입니다. 글꼴이 뭔가 어색하고, 특히 모바일에서 보면 마치 옛날 인터넷 익스플로러 시절처럼 보였습니다. 제 제자들도 “교수님, 폰트가 좀 이상해요”라고 말했으니까요.
처음엔 마크다운 문제라고 생각했고, 다음엔 Jekyll 버전 문제라고 생각했습니다. 심지어 GitHub Pages 서버의 문제라고까지 의심했습니다. 하지만 진짜 답은 훨씬 간단한 곳에 있었습니다. CSS에서 웹폰트 설정을 제대로 못 했던 것입니다.
Jekyll Chirpy 테마에서 한글 폰트를 제대로 적용하기
문제의 근원
Jekyll Chirpy 테마는 기본적으로 영문 폰트(산세리프, Roboto 등)에 최적화되어 있습니다. 하지만 한글은 영문과 다릅니다. 한글은 초성, 중성, 종성의 조합으로 만들어지기 때문에, 서체 자체가 훨씬 복잡합니다. 영문 글꼴을 그냥 한글에 적용하면, 브라우저가 임의로 대체 글꼴을 선택하게 되는데, 이게 바로 그 이상한 느낌을 만드는 것입니다.
저는 처음 이걸 몰랐습니다. 제 노트북의 로컬 환경에서는 시스템 한글 폰트가 자동으로 적용되기 때문에 문제가 보이지 않았거든요. 하지만 다른 컴퓨터에서 보면 완전히 달랐습니다.
해결 방법: assets/css/style.scss 수정
Chirpy 테마의 CSS 파일을 수정해야 합니다. _sass/main.scss 또는 assets/css/style.scss를 열어서, body나 기본 폰트 설정 부분에 다음과 같이 한글 폰트를 우선순위로 추가합니다:
1
2
3
4
5
body {
font-family: 'Noto Sans KR', 'Noto Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
여기서 중요한 점은 폰트 순서입니다. 한글 폰트(‘Noto Sans KR’)를 가장 앞에 놓아야 브라우저가 먼저 이걸 시도합니다. 그 다음에 영문 폰트를 배치합니다.
Google Fonts에서 웹폰트 가져오기
하지만 폰트를 지정하는 것만으로는 부족합니다. 사용자의 컴퓨터에 ‘Noto Sans KR’이 설치되어 있지 않을 수 있기 때문입니다. 그래서 웹폰트를 사용해야 합니다.
_includes/head.html 파일에 다음 링크를 추가합니다:
1
2
3
<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;500;700&display=swap" rel="stylesheet">
preconnect를 사용하는 것은 성능 최적화입니다. 미리 연결을 설정하면 폰트 로딩이 빨라집니다. 저는 처음에 이 부분을 몰라서 폰트가 늦게 로드되는 바람에 사용자들이 처음엔 기본 폰트가 보였다가 나중에 바뀌는 현상(FOUT, Flash of Unstyled Text)을 겪게 했습니다.
모바일 환경에서 테스트하는 것의 중요성
제가 이 문제를 5년이나 놓쳤던 이유 중 하나는, 주로 데스크톱에서만 테스트했기 때문입니다. 교수 시절 습관처럼, 큰 모니터에서만 확인했던 것이지요.
그런데 제 외손주가 태블릿으로 할아버지 블로그를 보겠다고 했을 때, 비로소 문제를 깨달았습니다. 모바일 크롬에서는 정말 끔찍했습니다.
Chrome DevTools를 활용한 검증
요즘에는 데스크톱 Chrome에서 F12를 눌러서 Device Toolbar를 켜면, 모바일 환경을 쉽게 시뮬레이션할 수 있습니다. 아이폰 12, 삼성 Galaxy S21 등 여러 기기를 선택해서 테스트할 수 있거든요.
저는 이제 포스트를 작성할 때마다:
- 데스크톱 화면에서 확