PaperMod에서 Stack 테마로 갈아타며 배운 것들

블로그 테마를 PaperMod에서 Stack(CaiJimmy/hugo-theme-stack)으로 교체했다. 색은 무채색(zinc) 톤으로, 폰트는 Pretendard로 커스텀했다. 단순히 “옷 갈아입기"로 끝나는 작업이 아니라 글 메타데이터와 자동화 prompt까지 한 사이클로 묶어야 일이 닫힌다는 걸 새삼 느꼈다. 헤맸던 지점 위주로 정리한다.

테마 붙이고 config에서 처음에 헤매는 것들

Stack은 submodule로 붙인다.

1
git submodule add https://github.com/CaiJimmy/hugo-theme-stack themes/hugo-theme-stack

GitHub Actions로 빌드한다면 checkout 단계에 submodules: recursive 옵션이 있어야 테마가 같이 받아진다. 이게 없으면 로컬에선 멀쩡한데 배포 빌드만 깨진다.

hugo.toml은 길지만, 처음에 발목 잡히는 건 세 가지뿐이다.

mainSections = ["posts"] — Stack 기본값은 단수형 "post"다. 우리 폴더가 posts/라면 이걸 명시하지 않으면 홈에 글이 한 개도 안 뜬다.
sidebar.avatar는 문자열 한 줄로. {enabled=..., src=...} 같은 중첩 테이블을 쓰면 빌드 에러가 난다.
메뉴 아이콘은 실재하는 파일명으로. themes/.../assets/icons/에 실제로 있는 이름이어야 한다. list, category처럼 없는 이름을 쓰면 빌드가 fail한다. archives, categories, tag, hash, home 정도가 안전하다.

커스텀의 90%는 custom.scss 한 파일에서 끝난다

Stack은 자기 style.scss 마지막에 @import "custom.scss";를 박아둔다. 그래서 우리 사이트의 assets/scss/custom.scss만 만들면 별도 설정 없이 자동으로 끼워져 컴파일된다. 이게 Stack 커스텀의 핵심이다.

이 파일에서 한 일은 다음과 같다.

색 변수(--body-background, --accent-color, --card-background 등)를 라이트/다크 모두 zinc 톤으로 override. 다크 모드는 :root[data-scheme="dark"] 블록에서 따로 잡는다.
Pretendard를 @import url(...) CDN으로 불러오고 --base-font-family를 교체. Stack 기본 폰트인 Lato는 한글 글리프가 없어서 시스템 fallback으로 떨어지면 글자가 둔탁해진다.
카드 타이틀을 2.2rem → 1.9rem으로 줄이고 letter-spacing: -0.01em. 한글은 영문보다 자간을 살짝 좁히는 쪽이 균형이 맞는다.
본문에 word-break: keep-all; overflow-wrap: anywhere; — 한국어가 어절 단위로 줄바꿈되어 훨씬 깔끔해진다.

가장 큰 함정: 카테고리 배지의 inline style

제일 오래 잡아먹은 건 카테고리/태그 배지였다. Stack은 카테고리·태그마다 hash로 색을 자동 생성해서 <a> 태그에 inline style로 직접 박는다. inline style은 외부 CSS를 이기기 때문에, SCSS로 그냥 덮어쓰면 먹지 않는다.

해결은 !important로 강제하는 것이다.

1
2
3
4
.article-category a, .article-tags a {
    background-color: var(--card-background-selected) !important;
    color: var(--card-text-color-secondary) !important;
}

이걸 안 하면 사이트 전체는 무채색인데 카테고리 배지만 알록달록하게 튄다.

글 메타데이터와 자동화 prompt까지 함께 손보기

Stack 사이드바의 카테고리 위젯이 살아나려면 각 글의 frontmatter에 categories:가 있어야 한다. 기존 글들은 PaperMod 시절이라 tags:만 있어서 위젯이 비어 있었다. 그래서 모든 글에 카테고리를 VLA / 피지컬 AI / 메타 3개 분류로 채워 넣었다.

여기서 멈추면 다음 날 새로 생기는 글에서 같은 문제가 반복된다. 그래서 매일 밤 자동 초안을 만드는 prompt-instructions.txt에도 categories 지시를 추가했다. 이제 다음 날부터 새 글은 자동으로 올바른 분류에 들어간다. 테마 교체를 글 메타데이터·자동화 prompt까지 한 사이클로 묶어야 일이 닫힌다는 게 이 작업의 교훈이다.

작업 흐름에서 챙긴 팁도 적어둔다.

별도 브랜치에서 작업. main은 머지 시점까지 건드리지 않는다.
로컬에서 hugo server를 띄워두고 SCSS를 고치면 hot reload된다. 확인할 때마다 GitHub Pages에 push하지 말 것.
배포 후 옛 모양으로 보이면 십중팔구 브라우저 캐시다. Ctrl+Shift+R이나 시크릿 창으로 먼저 확인하자. 빌드 자체를 의심하기 전에 curl로 라이브 CSS에 새 규칙이 들어갔는지 보는 게 더 빠르다.

한 줄 정리

Stack 테마 교체의 핵심은 custom.scss 한 파일과 inline style을 이기는 !important이며, 테마 변경은 글 메타데이터와 자동화 prompt까지 한 사이클로 묶어야 비로소 끝난다.