Hugo 운영 기록
Hugo로 만든 정적 사이트를 운영하면서 걸린 문제를 모은 곳입니다. 버전을 올렸을 때 바뀐 템플릿 조회 규칙과 설정 키, sitemap·RSS·구조화 데이터처럼 검색엔진이 읽는 출력, 이미지와 코드 블록 처리, 예약 발행에서 날짜와 시간대가 어긋나는 문제를 다룹니다.
글마다 재현에 쓴 Hugo나 도구의 버전을 본문에 적었습니다. 같은 증상이라도 버전이 다르면 원인이 다를 수 있으니 본문의 버전과 쓰고 계신 버전을 먼저 맞춰 보시기 바랍니다.
글 23편
구글 검색결과에 내 블로그 파비콘이 안 뜬다면: favicon.ico가 404였고, '48px 배수'는 지금 기준이 아니었습니다
구글 검색결과에 파비콘이 안 뜰 때 크기부터 의심하기 쉽습니다. 제 블로그는 favicon.ico가 404였고, 커뮤니티 답변에 인용된 '48px의 배수' 규칙은 2024년 말 개정 전 문구였습니다. Hugo에서 고친 과정을 적었습니다.
읽기 →Hugo 메뉴에 현재 페이지 active가 안 붙을 때: url 대신 pageRef를 써야 합니다
hugo.toml 메뉴를 url로 적으면 IsMenuCurrent와 HasMenuCurrent가 제가 본 다섯 페이지에서 모두 false였습니다. 블로그 사본에서 재현하고 pageRef로 바꿔 active·ancestor가 갈리는 것까지 확인했습니다.
읽기 →Hugo RSS를 전문으로 바꿨더니 이미지 주소는 멀쩡했고, 포럼식 CDATA에서만 깨졌습니다
Hugo 내장 RSS의 .Summary를 .Content로 바꿔 피드 용량과 상대 경로를 쟀습니다. 슬래시로 시작하는 주소는 Hugo가 알아서 절대 주소로 바꾸지만 CDATA로 감싸면 그 변환이 꺼지고, 각주·번들 이미지는 끝까지 남았습니다.
읽기 →languageCode 경고를 지우려고 locale로 바꿨더니 구버전 빌드에서 깨집니다
Hugo 0.158부터 languageCode는 locale로 바뀌었습니다. 0.147.7과 0.157~0.165, 열 개 버전으로 빌드해 보니, 오류는 설정 키가 아니라 템플릿의 .Locale에서 났고 설정 키는 오류 없이 값만 바꿨습니다.
읽기 →예전 글의 틀린 문장을 고쳤는데, 독자에게 남은 건 「9월 갱신」 한 줄이었습니다
블로그 글을 고친 뒤 화면의 갱신일, 구조화 데이터 dateModified, sitemap lastmod를 18편에서 맞춰 봤습니다. 날짜는 셋 다 맞았지만 무엇을 고쳤는지는 어디에도 없어서 정정 내역을 남기는 틀을 만들었습니다.
읽기 →오늘 날짜로 쓴 Hugo 글이 아침 9시까지 안 보입니다 — timeZone을 넣고 시각별로 재 봤습니다
시각 없이 date만 적은 Hugo 글은 한국 시각 09:00 전까지 빌드에서 빠집니다. timeZone을 넣으면 무엇이 바뀌고 무엇이 안 바뀌는지, 빌드 시각을 고정해 두 설정으로 재 봤습니다.
읽기 →Hugo 이미지 render hook에서 figure를 냈더니 p 안에 들어가 있었습니다
render-image.html에서 figure를 내면 Hugo는 기본값으로 그걸 p로 감쌉니다. 설정 한 줄과 .IsBlock 분기로 132개를 0개로 만들었고, 링크로 감싼 이미지는 그래도 남는다는 걸 확인했습니다.
읽기 →Hugo sitemap에서 페이지 하나를 뺐는데, 어떤 표기는 경고 없이 무시됐습니다
Hugo의 sitemap.disable을 표기 13가지, 섹션·cascade·커스텀 템플릿 조합으로 빌드해 봤습니다. 빠지는 경우와 경고 없이 무시되는 경우, sitemap에서 빠져도 색인은 막지 못한다는 점을 정리했습니다.
읽기 →출처로 걸어둔 외부 링크가 죽어도 블로그는 아무 말을 하지 않았습니다
Hugo 빌드 결과물 전체를 lychee로 훑었습니다. 외부 링크 76개 중 에러는 1건이었는데 죽은 링크가 아니었고, 정작 봐야 할 것은 OK로 통과한 리다이렉트 속에 있었습니다. 주간 점검 설정까지 적었습니다.
읽기 →Hugo 코드 블록에 색이 하나도 없었습니다: noClasses=false로 두고 Chroma CSS를 안 만들었습니다
noClasses=false 설정은 HTML에 색 이름표만 붙이고, 실제 색은 따로 만든 CSS가 칠합니다. 그 CSS가 없어서 코드 1,218개 토큰이 전부 단색이었습니다. 기본 명령으로 만든 CSS를 붙였더니 다크 모드에서 글자가 사라졌습니다.
읽기 →Hugo ld+json에 '문자열의 이스케이프 시퀀스가 잘못됨'이 뜰 때, 지금 버전에서는 포럼의 해결책이 원인이었습니다
제목에 &·따옴표·백슬래시가 든 글에서만 구조화된 데이터가 깨집니다. Hugo 16개 버전과 템플릿 9가지로 재현해 보니, 지금 Hugo에서 깨지는 쪽은 기본 문법이 아니라 printf와 safeJS로 따옴표를 손으로 붙인 코드였습니다.
읽기 →Hugo 블로그 링크를 카톡에 보내면 썸네일이 없을 때 — og:image와 카카오 캐시
카톡 미리보기에 그림이 붙으려면 og:image가 있어야 하는데, 제 블로그 글 head에는 그 태그가 아예 없었습니다. 대표 이미지를 og:image로 내보내고 WebP와 JPG 출력을 비교했고, 카카오 캐시를 지우는 곳까지 적었습니다.
읽기 →Hugo static/에 둔 이미지는 원본 그대로 나갑니다 — 빌드 때 줄이고 WebP로 바꾸기
static/ 의 이미지는 Hugo가 건드리지 않습니다. assets/ 로 옮겨 render-image 훅에서 Resize 하자 PNG 약 7.2MB가 1280px WebP 약 0.18MB가 됐습니다. 첫 빌드가 느린 이유와 resources/_gen 캐시도 봤습니다.
읽기 →Hugo 0.146 이후 _default 와 partials 를 옮기다가 태그 페이지가 전부 비었습니다
옛 layouts 구조는 최신 Hugo 에서도 대부분 그대로 돕니다. 문제는 옮기는 도중입니다. 0.145.0 과 0.165.0 으로 한 단계씩 옮겨 빌드하며 무엇이 조용히 바뀌는지 쟀습니다.
읽기 →Hugo RSS에 lastBuildDate가 없고, 개인정보처리방침이 0001년 글로 섞여 있었습니다
Hugo 기본 RSS는 홈 페이지의 날짜가 비면 lastBuildDate를 빼는데, git 정보를 켜고 _index.md를 커밋하면 그 날짜가 빕니다. 날짜 없는 페이지가 0001년으로 피드에 들어가는 문제와 함께 내장 템플릿을 덮어써 고쳤습니다.
읽기 →Hugo 한국어 제목의 목차 링크가 #원인--파일 처럼 하이픈 두 개로 나왔습니다
Hugo의 autoIDType 세 값(github, github-ascii, blackfriday)으로 같은 한국어 제목을 빌드해 id와 목차 링크를 비교했습니다. 공유 주소가 인코딩되는 모습과 {#id}로 고정하는 법까지 확인했습니다.
읽기 →글을 고쳤는데 sitemap 의 lastmod 가 발행일에 멈춰 있었습니다
Hugo 에서 enableGitInfo 를 켜고 Actions 의 fetch-depth: 0 을 짝으로 맞춰야 sitemap lastmod 가 커밋 시각이 됩니다. 얕은 클론과 목록 페이지에서 걸린 것까지 재서 적었습니다.
읽기 →Sveltia CMS가 선언 안 한 프론트매터 키를 지운다고 적어뒀는데, 지우는 쪽은 따로 있었습니다
config.yml에 안 적은 키는 저장할 때 사라진다고 주석까지 달아뒀습니다. 코드를 직접 돌려보니 그 키는 남았고, 값이 실제로 망가지는 건 위젯을 잘못 골라 선언했을 때였습니다.
읽기 →hasCJKLanguage 한 줄에 단어 수가 세 배, 요약은 한 문단으로 줄었습니다
한국어 Hugo 블로그 글 12편을 hasCJKLanguage를 끄고 켜서 두 번 빌드했습니다. 단어 수는 2.5~3.2배, 읽는 시간은 0~2분 늘었고, 요약 길이 편차는 설정보다 첫 문단 길이에서 왔습니다.
읽기 →Hugo 글을 draft로 내렸는데, 그 글로 가는 링크는 빌드가 아무 말도 안 했습니다
일반 마크다운 링크는 대상 글이 사라져도 빌드가 조용히 통과합니다. ref 숏코드와 직접 만든 render-link 훅으로 깨질 링크를 빌드 단계에서 잡은 과정과 실측 결과를 적었습니다.
읽기 →Hugo가 없는 맥에서, 설치하지 않고 정해진 버전으로 한 번만 빌드해 봤습니다
macOS용 Hugo는 이제 압축 파일이 아니라 .pkg 설치 프로그램으로만 나옵니다. 설치 프로그램을 열지 않고 pkgutil로 바이너리만 꺼내서, 버전을 고정해 한 번 빌드하고 지우는 절차를 처음부터 다시 돌려 잰 기록입니다.
읽기 →글 목록을 여섯 편씩 끊었습니다 — 틀려도 조용한 것들
지금 Hugo 에서 옛 설정 키는 무시되는 대신 내장 기본값 10 으로 떨어졌고, 2페이지는 canonical 로 자기가 1페이지라고 말하고 있었습니다. 빌드가 죽는다고 적어뒀던 근거 하나는 재현해보니 틀려서 주석부터 고쳤습니다.
읽기 →Astro로 만든 사이트를 하루 만에 Hugo로 갈아엎었습니다
먼저 고른 쪽이 틀렸습니다. 대안을 나란히 놓고 따져보지 않았기 때문입니다. 다시 고르면서 실제로 잰 숫자들과, 결정을 가른 질문 하나를 적어둡니다.
읽기 →