birchholt 직접 해보고 남기는 기록

운영 기록

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

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

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

· Hugo

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

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

읽기 →
· Hugo

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

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

읽기 →
· Hugo

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

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

읽기 →
· Hugo

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

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

읽기 →
· Cloudflare·배포

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

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

읽기 →
· Hugo

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

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

읽기 →