이 문서는 다음 유지보수자를 위한 인수인계 기록이다.

이번 패스의 핵심은 문자열, 메뉴, 언어 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 내부 문서는 앞으로도 변경 범위가 커질 때마다 계속 갱신해야 한다.

관련 원본 위치

  • 디자인 토큰: 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/