이 문서는 다음 유지보수자를 위한 인수인계 기록이다.
이번 패스의 핵심은 문자열, 메뉴, 언어 URL 정책을 모두 중앙화해서, 나중에 언어가 더 늘어나도 같은 규칙으로 확장할 수 있게 만드는 것이다.
이번 패스의 핵심 수정
1) 콘텐츠 검증 랩을 다시 설계
content/ko/blog/theme-upgrade-lab/전체를 검증용 스테이지로 재정리했다.- 설명형 문서가 아니라 실제 프런트엔드 렌더링을 직접 확인하는 포스트 세트로 바꾸었다.
- Markdown 기본문법, CTA, figure, collapse, raw HTML, bidi, page bundle 리소스를 각 페이지에서 분리해 검증할 수 있게 했다.
2) theme-vars.css를 기준으로 한 디자인 검증 구조 강화
- 디자인 값은 콘텐츠에서 흩어져 있지 않고, 중앙 토큰 파일을 읽는 방식으로 설명되도록 정리했다.
design-tokens.md,color-surface.md,layout-spacing.md,typography-language.md를 통해 토큰 → 화면 결과를 연결했다.- 같은 토큰이 카드, 버튼, 표면, 표, 코드, figure에 어떻게 내려가는지 한눈에 보이게 했다.
3) CTA 정책과 컴포넌트 문서의 분리
- CTA는
config/_default/params.toml의[params.cta.*]를 원본으로 보고, 콘텐츠에서는 사용 예시와 렌더링 결과만 확인하게 했다. - 버튼/카드/미디어/숏코드 조합을 각각 별도 페이지로 분리해서 문제 위치를 빠르게 좁힐 수 있게 했다.
kind기반 preset,href/ref정책,_blank와rel관계를 실제 프런트엔드 기준으로 검토할 수 있도록 했다.
4) page bundle 리소스 테스트 강화
04-architecture/bundles-resources/안에cover.svg와diagram.svg를 함께 두어, 본문과 리소스가 같은 수명주기를 갖도록 정리했다.- 상대경로 리소스가 페이지 번들 안에서 정상적으로 읽히는지 확인할 수 있다.
- 섹션 커버와 다이어그램이 실제 렌더링에서 어떤 크기와 비율로 보이는지 점검할 수 있다.
5) 운영 문서를 배포 기준으로 정리
verification-log.md는 체크리스트 역할을 하도록,update-log.md는 변경 이력 역할을 하도록 분리했다.upgrade-summary.md는 전체 구조를 빠르게 훑는 요약문으로 둔다.- 나중에 추가 문서가 생겨도 이 구분을 그대로 유지하는 것이 좋다.
이번에 수정한 트리 구조
content/ko/blog/theme-upgrade-lab/
├── _index.md
├── 00-full-coverage.md
├── 01-foundation/
│ ├── _index.md
│ ├── design-tokens.md
│ ├── color-surface.md
│ ├── layout-spacing.md
│ └── typography-language.md
├── 02-components/
│ ├── _index.md
│ ├── controls-cards.md
│ ├── cta-shortcode.md
│ └── media-figure.md
├── 03-rendering/
│ ├── _index.md
│ ├── markdown-rendering.md
│ ├── shortcode-composition.md
│ └── edge-cases.md
├── 04-architecture/
│ ├── _index.md
│ ├── taxonomy-navigation.md
│ └── bundles-resources/
│ ├── index.md
│ ├── cover.svg
│ └── diagram.svg
├── 05-operations/
│ ├── _index.md
│ ├── update-log.md
│ ├── verification-log.md
│ └── upgrade-summary.md
└── 06-public-posts/
├── _index.md
├── 01-productivity-routine.md
├── 02-budget-guide.md
├── 03-weekend-cleanup.md
└── 04-travel-checklist.md
주의사항
theme-vars.css대신 콘텐츠 안에서 색상/간격/서체를 하드코딩하지 않는다.- CTA 문구를 콘텐츠마다 제멋대로 새로 정의하지 말고,
params.toml의 preset을 우선 사용한다. - page bundle 리소스는 다른 위치로 옮기지 않는 것이 안전하다.
- 다른 언어의 파일명/트리는 유지하되, ko가 가장 먼저 검증될 수 있도록 내용을 풍부하게 두는 것이 좋다.
update-log내부 문서는 앞으로도 변경 범위가 커질 때마다 계속 갱신해야 한다.
이번 패스에서 추가한 공지 / 배너 / 팝업 시스템
핵심 파일
config/_default/params.tomlthemes/(0000-0000-0000-0001)/layouts/partials/theme/announcement.htmlthemes/(0000-0000-0000-0001)/assets/css/common/announcement.cssthemes/(0000-0000-0000-0001)/assets/css/core/theme-vars/80-announcement.cssthemes/(0000-0000-0000-0001)/assets/css/core/theme-vars.css
왜 새 모듈로 분리했는가
- 공지 문구와 노출 조건은 설정 파일에서만 바꿀 수 있어야 한다.
- 색상, 여백, 레이어, 반응형 규칙은 theme-vars 토큰으로만 조절해야 한다.
- banner / modal(popup) / toast 를 같은 선택 규칙으로 관리하면 유지보수가 쉬워진다.
이번 구조의 동작 방식
params.toml에서 공지 후보를 여러 개 정의한다.- partial 이 현재 언어, kind, section, taxonomy, path, page params 를 확인한다.
- 가장 높은 priority 를 가진 항목 1개만 렌더링한다.
- 닫기 동작은 localStorage / sessionStorage / none 으로 제어한다.
- 디자인은 CSS 하드코딩이 아니라 theme-vars 토큰을 통해서만 바뀐다.
트리 구조 변경
config/_default/
├── hugo.toml
├── languages.cn.toml
├── languages.en.toml
├── languages.jp.toml
├── languages.ko.toml
└── params.toml
themes/(0000-0000-0000-0001)/
├── assets/
│ └── css/
│ ├── common/
│ │ └── announcement.css
│ └── core/
│ ├── theme-vars.css
│ └── theme-vars/
│ └── 80-announcement.css
└── layouts/
├── _default/
│ └── baseof.html
└── partials/
└── theme/
└── announcement.html
주의사항
- 배너 문구를 페이지 본문에 직접 박아 넣지 않는다.
- 특정 언어만 겨냥하는 값이 필요하면 item 의
languages만 바꾸고 코드 경로는 건드리지 않는다. - 팝업을 사용할 때는
storage = "session"또는storage = "local"을 의도에 맞게 고른다. enabled = false항목은 샘플로 남겨 두고, 운영 배포 전까지는 그대로 비활성 상태를 유지하는 편이 안전하다.
관련 원본 위치
- 디자인 토큰:
themes/(0000-0000-0000-0001)/assets/css/core/theme-vars.css - CTA 정책:
config/_default/params.toml - 숏코드 렌더링:
themes/(0000-0000-0000-0001)/layouts/shortcodes/ - page bundle 리소스:
content/ko/blog/theme-upgrade-lab/04-architecture/bundles-resources/