birchholt 직접 해보고 남기는 기록

운영 기록

이 자리에 모인 글은 전부 제가 직접 걸려서 재본 것들입니다. 읽고 정리한 것이 아니라, 안 되는 화면을 앞에 두고 원인을 찾을 때까지 재본 기록입니다. 그래서 주제가 예쁘게 이어지지 않습니다. 티스토리 스킨 치환자 이야기 다음에 GitHub Actions 스케줄 이야기가 오고, 그 다음이 다시 도메인 이야기입니다. 막힌 순서대로 쌓았기 때문입니다.

쓸 때 지키는 것이 세 가지 있습니다. 첫째, 숫자는 어떻게 쟀는지 같이 적습니다. “느리다"가 아니라 몇 초였고 무엇으로 쟀는지를 적습니다. 둘째, 틀렸던 것은 지우지 않고 정정합니다. 처음에 세운 가설이 실측에서 깨지면 그 과정을 남깁니다 — 틀린 경로를 지워버리면 다음 사람이 같은 곳에 다시 들어갑니다. 셋째, 확인하지 못한 것은 확인하지 못했다고 적습니다. 그럴듯하게 채우면 읽는 사람이 검증하는 데 드는 시간이 제가 아낀 시간보다 커집니다.

공식 문서가 이미 잘 설명하는 것은 여기 없습니다. 문서와 실제가 어긋난 지점, 문서 문장을 제가 잘못 읽었던 지점, 그리고 로컬에서는 멀쩡한데 라이브에서만 깨지던 것들이 남았습니다. 같은 데서 막힌 사람이 검색으로 닿기를 바라며 적습니다.

2026년 10월 · Hugo

Hugo 코드 블록에 색이 하나도 없었습니다: noClasses=false로 두고 Chroma CSS를 안 만들었습니다

noClasses=false 설정은 HTML에 색 이름표만 붙이고, 실제 색은 따로 만든 CSS가 칠합니다. 그 CSS가 없어서 코드 1,218개 토큰이 전부 단색이었습니다. 기본 명령으로 만든 CSS를 붙였더니 다크 모드에서 글자가 사라졌습니다.

읽기 →
2026년 10월 · Hugo

Hugo ld+json에 '문자열의 이스케이프 시퀀스가 잘못됨'이 뜰 때, 지금 버전에서는 포럼의 해결책이 원인이었습니다

제목에 &·따옴표·백슬래시가 든 글에서만 구조화된 데이터가 깨집니다. Hugo 16개 버전과 템플릿 9가지로 재현해 보니, 지금 Hugo에서 깨지는 쪽은 기본 문법이 아니라 printf와 safeJS로 따옴표를 손으로 붙인 코드였습니다.

읽기 →
2026년 10월 · Cloudflare

Hugo 블로그 링크를 카톡에 보내면 썸네일이 없을 때 — og:image와 카카오 캐시

카톡 미리보기에 그림이 붙으려면 og:image가 있어야 하는데, 제 블로그 글 head에는 그 태그가 아예 없었습니다. 대표 이미지를 og:image로 내보내고 WebP와 JPG 출력을 비교했고, 카카오 캐시를 지우는 곳까지 적었습니다.

읽기 →
2026년 10월 · Hugo

Hugo static/에 둔 이미지는 원본 그대로 나갑니다 — 빌드 때 줄이고 WebP로 바꾸기

static/ 의 이미지는 Hugo가 건드리지 않습니다. assets/ 로 옮겨 render-image 훅에서 Resize 하자 PNG 약 7.2MB가 1280px WebP 약 0.18MB가 됐습니다. 첫 빌드가 느린 이유와 resources/_gen 캐시도 봤습니다.

읽기 →
2026년 10월 · Cloudflare

커스텀 도메인을 붙여도 pages.dev 주소는 계속 열려 있습니다

커스텀 도메인을 붙인 뒤에도 프로젝트.pages.dev 주소가 같은 내용을 noindex 없이 내주고 있었습니다. _headers 규칙을 미리보기 배포로 먼저 시험하고, production에 넣은 뒤 두 주소의 헤더를 다시 찍었습니다.

읽기 →
2026년 10월 · Hugo

Hugo 0.146 이후 _default 와 partials 를 옮기다가 태그 페이지가 전부 비었습니다

옛 layouts 구조는 최신 Hugo 에서도 대부분 그대로 돕니다. 문제는 옮기는 도중입니다. 0.145.0 과 0.165.0 으로 한 단계씩 옮겨 빌드하며 무엇이 조용히 바뀌는지 쟀습니다.

읽기 →