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

이번 업그레이드의 핵심은 content만 전면 재설계해서, 프런트엔드 렌더링 검증이 가능한 구조로 다시 짠 것이다.
코드와 테마 파일은 건드리지 않고, 콘텐츠만으로 실제 UI·문법·언어·분류를 확인할 수 있도록 정리했다.

유지한 원칙

  • 폴더 트리와 파일명은 유지한다.
  • 내용을 삭제해도 되는 파일은 내부 본문만 갈아엎는다.
  • 한국어를 기준 언어로 두고, 나머지 언어는 구조 동기화에 집중한다.
  • 디자인과 UI의 실제 기준은 theme-vars 계층에 둔다.
  • 페이지 본문은 설명문이면서 동시에 시각적 테스트 시트가 되어야 한다.

이번 패스에서 새로 강화한 점

1) 검증용 페이지를 실제 렌더링 시트로 전환

기존에는 기능 설명 위주였다면, 이번에는 실제 화면에서 어떻게 보이는지 바로 점검할 수 있도록 바꿨다.

  • Markdown 기본 문법을 분리해서 확인한다.
  • CTA, figure, collapse, raw HTML, inline image를 실제로 배치한다.
  • 언어별 폰트와 RTL 방향성도 함께 검증한다.

2) 디자인 토큰을 문서형 설명에서 시각형 점검으로 전환

design-tokens.md는 단순 설명이 아니라,
모듈별 변수 수, 샘플 카드, 전체 변수 목록을 동시에 보여 주는 카탈로그가 됐다.

3) 페이지 번들과 리소스 경로를 실물로 확인

04-architecture/bundles-resources/index.md는 같은 번들 안의 cover.svg, diagram.svg를 직접 불러와서 페이지 리소스 연결을 테스트한다.

4) 공개 글도 실제 포스팅처럼 보이게 정리

06-public-posts/ 아래 글은 검증 문서보다 덜 딱딱하고, 실제 독자가 읽는 글처럼 보이게 문단 리듬과 CTA를 조정했다.

트리 구조 요약

content/
├─ ko/
│  ├─ _index.md
│  ├─ about/_index.md
│  ├─ blog/_index.md
│  ├─ blog/theme-upgrade-lab/
│  │  ├─ 00-full-coverage.md
│  │  ├─ 01-foundation/
│  │  │  ├─ _index.md
│  │  │  ├─ color-surface.md
│  │  │  ├─ design-tokens.md
│  │  │  ├─ layout-spacing.md
│  │  │  └─ typography-language.md
│  │  ├─ 02-components/
│  │  │  ├─ _index.md
│  │  │  ├─ controls-cards.md
│  │  │  ├─ cta-shortcode.md
│  │  │  └─ media-figure.md
│  │  ├─ 03-rendering/
│  │  │  ├─ _index.md
│  │  │  ├─ edge-cases.md
│  │  │  ├─ markdown-rendering.md
│  │  │  └─ shortcode-composition.md
│  │  ├─ 04-architecture/
│  │  │  ├─ _index.md
│  │  │  ├─ bundles-resources/index.md
│  │  │  └─ taxonomy-navigation.md
│  │  ├─ 05-operations/
│  │  │  ├─ _index.md
│  │  │  ├─ update-log.md
│  │  │  ├─ upgrade-summary.md
│  │  │  └─ verification-log.md
│  │  └─ 06-public-posts/
│  │     ├─ _index.md
│  │     ├─ 01-productivity-routine.md
│  │     ├─ 02-budget-guide.md
│  │     ├─ 03-weekend-cleanup.md
│  │     └─ 04-travel-checklist.md
│  ├─ categories/_index.md
│  ├─ contact/_index.md
│  └─ tags/_index.md
├─ en/
├─ jp/
└─ cn/

주의사항

  • 이 업그레이드는 content 전용이다.
  • theme-vars.css와 config/_default/params.toml의 구조는 코드 레이어에서 유지되는 전제다.
  • 나중에 README를 쓸 때는 이 문서를 기준으로 변경 이유를 덧붙이면 된다.

검증 기준

  • 한국어 페이지가 가장 풍부하게 렌더링되는가
  • 다른 언어는 같은 트리와 같은 식별자를 유지하는가
  • 업데이트 로그만 읽어도 무엇이 바뀌었는지 바로 파악되는가