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

이번 패스의 핵심은 문자열, 메뉴, 언어 URL 정책을 모두 중앙화해서, 나중에 언어가 더 늘어나도 같은 규칙으로 확장할 수 있게 만든 것이다.

이번 패스의 핵심 수정

1) 콘텐츠 검증 범위를 content/ko/blog/theme-upgrade-lab 로 집중

파일:

  • content/ko/blog/theme-upgrade-lab/*

변경 내용:

  • 검증용 콘텐츠를 한국어 우선으로 재설계했다.
  • 실제 프런트엔드에서 보이는 결과를 기준으로 문법, 컴포넌트, 번들, 택소노미를 다시 구성했다.
  • 각 문서는 설명문이면서 동시에 화면 확인용 샘플이 되도록 내용을 늘렸다.

중요한 이유:

  • 읽는 사람 입장에서는 설명이, 유지보수자 입장에서는 스펙이 된다.
  • 특정 페이지 설명에만 머무르지 않고 실제 렌더 결과를 바로 볼 수 있다.

2) 디자인의 원본은 계속 theme-vars.css 만 보게 정리

파일:

  • themes/(0000-0000-0000-0001)/assets/css/core/theme-vars.css
  • themes/(0000-0000-0000-0001)/assets/css/core/theme-vars/*.css

변경 내용:

  • 색상, 간격, 반경, 컴포넌트, 서체의 해석을 콘텐츠에서 직접 확인하도록 구조를 맞췄다.
  • 콘텐츠 쪽에서는 값을 새로 만들지 않고, 중앙 토큰의 결과를 읽는 방식으로 설명을 쌓았다.

중요한 이유:

  • 디자인 변경의 단일 원본이 흔들리지 않는다.
  • 나중에 theme-vars 만 수정해도 같은 콘텐츠가 다른 결과를 보여준다.

3) 번들 자원은 page bundle 기준으로 확인

파일:

  • content/ko/blog/theme-upgrade-lab/04-architecture/bundles-resources/index.md
  • content/ko/blog/theme-upgrade-lab/04-architecture/bundles-resources/cover.svg
  • content/ko/blog/theme-upgrade-lab/04-architecture/bundles-resources/diagram.svg

변경 내용:

  • 이미지와 본문이 같이 움직이는지 검증할 수 있도록 같은 bundle 안에 자원을 두었다.
  • figure shortcode 로 캡션, 링크, 상대 경로를 모두 확인할 수 있게 했다.

중요한 이유:

  • 실제 배포에서는 경로가 콘텐츠와 같이 이동해야 한다.
  • 설명만 있는 문서보다 훨씬 빨리 오류를 잡을 수 있다.

4) Markdown과 shortcode 의 조합을 실제 문서로 증명

파일:

  • content/ko/blog/theme-upgrade-lab/03-rendering/*
  • content/ko/blog/theme-upgrade-lab/02-components/*

변경 내용:

  • 목록, 표, 코드, 인용, 각주, ltr/rtl, collapse, raw HTML, CTA, figure 를 서로 섞어도 안정적으로 보이도록 구성했다.
  • 기능 설명만 쓰지 않고 렌더 결과를 보는 문단을 늘렸다.

중요한 이유:

  • 단일 기능 테스트가 아니라 조합 테스트가 된다.
  • 실전에서는 대부분 기능이 겹쳐서 나온다.

5) 운영 문서를 배포 직전에 다시 읽을 수 있게 정리

파일:

  • content/ko/blog/theme-upgrade-lab/05-operations/update-log.md
  • content/ko/blog/theme-upgrade-lab/05-operations/upgrade-summary.md
  • content/ko/blog/theme-upgrade-lab/05-operations/verification-log.md

변경 내용:

  • 무엇이 바뀌었는지, 왜 바꿨는지, 무엇을 다시 확인해야 하는지를 분리했다.
  • 다시 열어봤을 때 바로 판단할 수 있는 구조로 바꿨다.

이번 패스에서 확인한 트리 구조

content/
└─ ko/
   ├─ _index.md
   ├─ blog/
   │  ├─ _index.md
   │  └─ 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
   │     │  ├─ 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

주의사항

  • 콘텐츠 외의 템플릿, CSS, JS 는 건드리지 않았다.
  • 디자인 컨트롤은 여전히 theme-vars 계층이 담당해야 한다.
  • root 레벨의 01-04 글은 public posts 의 별도 진입점으로 유지했다.

배포 전 마지막 확인

  • 홈, 소개, 연락, 블로그 목록이 모두 열리는가
  • 토큰 페이지의 색상/간격/폰트/반경이 실제 화면에서 보이는가
  • CTA, figure, collapse, raw HTML, ltr/rtl 이 모두 정상 동작하는가
  • page bundle 리소스가 상대 경로로 깨지지 않는가