Hugo를 이용해 블로그를 구축하면서 순탄하게 진행되는 듯했지만, 예상치 못한 두 가지 난관에 부딪혔다. 해결하고 보니 꽤 흥미로운 기술적 이유들이 숨어있어 이를 기록으로 남겨본다.
1. 2006년 1월 2일의 비밀 (Go 언어의 날짜 포맷)#
첫 번째 문제는 날짜 표시였다.
내가 사용하는 테마의 기본 날짜 표시는 Jan 2, 2006과 같은 영미권 방식이었다. 나는 이를 우리나라에서 흔히 쓰는 2025-12-21 같은 형식으로 직관적으로 바꾸고 싶어 설정 파일에 해당 형식을 입력했다.
단순히 문자열 포맷을 바꾸면 될 줄 알고 빌드를 했는데, 결과는 충격적이었다. 날짜가 4095-32-12 (정확한 숫자는 아니지만, 이처럼 터무니없는 값) 처럼 엉뚱하게 출력되고 있었다.
처음엔 당황해서 공식 홈페이지를 다시 정독했고, 그제야 원인을 알 수 있었다. Hugo는 Go 언어로 만들어졌고, Go 언어의 날짜 포맷팅 방식은 C언어나 다른 언어들의 방식(%Y, %MM 등)과는 완전히 달랐다.
Go Time Format 문서에 따르면, Go는 기준 시간(Reference Time)이라는 독특한 값을 포맷으로 사용한다.
Mon Jan 2 15:04:05 MST 2006
처음엔 “왜 하필 2006년이지?“라며 의아했지만, 숫자를 하나씩 뜯어보니 소름 돋는 규칙이 있었다.
- 1월 (Month)
- 2일 (Day)
- 오후 3시 (Hour, 24시간제로는 15시)
- 4분 (Minute)
- 5초 (Second)
- 2006년 (Year)
- GMT+07 (Timezone)
즉, 1, 2, 3, 4, 5, 6, 7 순서대로 매핑되어 있는 것이다.
기존 C 계열 언어에서 %M이 ‘달(Month)‘인지 ‘분(Minute)‘인지 헷갈리거나, 두 자리 표시는 어떻게 하는지 문서를 찾아봐야 했던 경험을 떠올려보면, 이는 고정된 날짜 하나만 기억하면 되는 매우 직관적이고 천재적인 방법이라는 생각이 들었다.
이 규칙을 이해한 뒤, 설정을 2006-01-02로 수정하여 원하던 날짜 형식을 얻을 수 있었다.
2. 한글 굵은 글씨(Bold) 렌더링 오류 (CJK 이슈)#
두 번째 문제는 Markdown 렌더링 관련 이슈였다.
분명히 마크다운 문법에 맞춰 **강조**라고 썼는데, 화면에는 굵은 글씨가 적용되지 않고 별표(*)가 그대로 노출되는 현상이 발생했다.
처음에는 폰트 문제이거나 CSS가 로딩되지 않은 문제라고 생각했다. 심지어 AI(Gemini)에게 물어봤을 때도 폰트 문제일 가능성을 제시하며 디버깅을 유도했다. 하지만 확인 결과, 굵은 글씨체 처리는 서버(Hugo)에서 마크다운을 HTML로 변환할 때 결정되는 것이지, 브라우저의 CSS나 폰트 문제가 아니었다.
문제의 원인은 Hugo가 사용하는 렌더링 엔진(Goldmark 등)이 CJK(한중일) 문자의 단어 경계를 인식하는 방식에 있었다.
- 영어: 알파벳은 단어 사이에 공백이 명확하여 파서가
**를 쉽게 인식한다. - 한글: 문장에 조사 등이 붙어 쓰이기 때문에, 파서가 한글 글자 사이에 끼인
**를 문법 요소가 아닌 단순 텍스트로 인식해버리는 경우가 많다.
마치 I_AM_HYUNJE라는 문구에서 _가 이탤릭체 문법으로 작동하지 않고 텍스트의 일부로 인식되는 것과 같은 이치다.
해결 방법#
이 문제를 해결하기 위해 찾은 방법은 크게 두 가지였다.
- 띄어쓰기 활용:
**앞뒤에 강제로 공백을 넣어 파서가 인식하게 한다. (예:이것은 **중요** 합니다) - 설정 변경:
goldmark.extensions.cjk.escapedSpace: true옵션을 켜고, 조사 앞에\(Escape) 공백을 사용한다.
나는 가독성과 호환성을 위해 별표 앞뒤에 띄어쓰기를 하는 습관을 들이는 것으로 해결했다.
재미있는 점은, 내가 도움을 청했던 Gemini(Google AI)의 채팅 화면에서도 동일한 버그(한글 굵은 글씨가 안 되고 별표가 보이는 현상)가 발생하고 있다는 것이다. 글로벌 기업인 구글의 서비스에서도 발생하는 문제라니, 리포트하기엔 너무 거대하고 복잡한 이슈인 것 같아 일단 쓴웃음을 지으며 넘어가기로 했다.
간단한 방법으로 맞춤법보다 볼드 출력이 우선이니, 단어 양옆은 강제로 띄워 써. 이렇게 알려주면 된다.
마치며#
블로그 하나를 만드는데도 언어적 설계 철학(Go의 날짜 포맷)과 문자 인코딩의 특성(CJK 렌더링)까지 이해해야 한다는 점이 번거롭기도 했지만, 덕분에 “당연하게 생각했던 것들이 사실은 당연하지 않다"는 개발자적 시각을 다시 한번 가다듬는 계기가 되었다.