이 문서는 이번 공지/배너 업그레이드의 기준 문서이다.

핵심 목표는 공지 문구, 노출 조건, 디자인 토큰, 닫기 동작을 모두 분리해서, 나중에 공지 유형이 늘어나도 같은 구조로 유지보수할 수 있게 만드는 것이다.

이번 패스의 핵심 수정

1) 공지/배너/모달의 중앙 통제를 config/_default/params.toml 에 추가

파일:

  • config/_default/params.toml

변경 내용:

  • [params.announcement] 를 새로 추가해 공지 기능 전체를 한 곳에서 켜고 끌 수 있게 만들었다.
  • enabled, defaultMode, defaultPlacement, defaultVariant, dismissible, persistDismissal, storageScope 를 공통 기본값으로 두었다.
  • [[params.announcement.items]] 로 실제 공지 샘플을 분리해, 같은 렌더러로 여러 유형을 재사용할 수 있게 했다.

중요한 이유:

  • 공지 문구를 템플릿 내부에 박아 넣지 않아도 된다.
  • 운영자가 수정해야 하는 값이 한 파일에 모여서 배포 속도가 빨라진다.
  • 유형별/하이어라키별/택소노미별 조건을 같은 구조로 관리할 수 있다.

2) 렌더러를 layouts/partials/theme/announcement.html 로 분리

파일:

  • themes/(0000-0000-0000-0001)/layouts/partials/theme/announcement.html

변경 내용:

  • 공지 선택, 조건 검사, 렌더링, 닫기, 저장소 처리까지 한 partial 안에 모았다.
  • banner, modal, inline 을 같은 렌더러로 처리하도록 만들었다.
  • 언어, kind, section, content prefix, taxonomy, term 을 조합해 노출 여부를 결정한다.

중요한 이유:

  • 페이지마다 다른 하드코딩을 쌓지 않아도 된다.
  • 공지 추가 시 파일을 복제할 필요 없이 config 만 늘리면 된다.
  • 닫기 기능과 세션/로컬 저장이 모든 공지 유형에 공통 적용된다.

3) 디자인 시스템은 theme-vars 계층만 수정

파일:

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

변경 내용:

  • 공지 전용 토큰과 레이아웃, 버튼, 모달 배경, 강조선 스타일을 theme-vars 계층에만 추가했다.
  • theme-vars.css 의 빌드 순서에 80-announcement.css 를 추가해 중앙 토큰 인덱스를 완성했다.
  • 배경색, 경계선, 여백, 그림자, 반응형 조정값을 모두 토큰 기반으로 관리하도록 정리했다.

중요한 이유:

  • 디자인은 config 나 페이지 본문에서 흩어지지 않는다.
  • 공지의 시각적 무게감을 유지하면서도 전체 테마와 충돌하지 않는다.
  • 나중에 같은 스타일 체계를 팝업, 토스트, 안내 카드로 확장할 수 있다.

4) 공지 텍스트는 theme i18n 으로 중앙화

파일:

  • themes/(0000-0000-0000-0001)/i18n/en.yaml
  • themes/(0000-0000-0000-0001)/i18n/ko.yaml
  • themes/(0000-0000-0000-0001)/i18n/jp.yaml
  • themes/(0000-0000-0000-0001)/i18n/cn.yaml

변경 내용:

  • 닫기, 자세히 보기 같은 공통 라벨과 공지 제목/본문/행동 문구를 테마 i18n 으로 옮겼다.
  • 한국어/영어/일본어/중국어 샘플을 같은 키 체계로 맞췄다.
  • 언어 추가 시에도 같은 키만 복제하면 되도록 구조를 정리했다.

중요한 이유:

  • 텍스트는 콘텐츠나 레이아웃에 섞이지 않는다.
  • 로케일별 공지 문구를 안전하게 바꿀 수 있다.
  • 기존 theme/i18n 구조와 완전히 같은 방식으로 유지된다.

5) baseof 에서 공지 렌더링 위치를 공통화

파일:

  • themes/(0000-0000-0000-0001)/layouts/_default/baseof.html

변경 내용:

  • 헤더 아래, 본문 위에 공지 partial 을 한 번만 주입했다.
  • 특정 페이지에만 별도 삽입하지 않고 모든 페이지가 같은 진입점을 쓰게 했다.

중요한 이유:

  • 레이아웃이 분기되지 않는다.
  • 전역 배너, 섹션 공지, 모달이 모두 같은 위치 정책을 공유한다.

이번에 추가한 샘플 공지

1) 사이트 공통 배너

  • 모든 언어/페이지에 노출되는 예시다.
  • 유지보수나 운영 상태가 바뀔 때 가장 먼저 쓰는 형태다.
  • 닫기 후 재노출 여부는 storageScope = "lang" 와 showOnce 로 조절한다.

2) 업데이트 로그용 인라인 공지

  • blog/theme-upgrade-lab/05-operations 경로 아래에서만 보이는 예시다.
  • 하이어라키 조건을 쓰는 전형적인 패턴이다.
  • 페이지 안에서 머무르며 읽는 안내에 적합하다.

3) taxonomy 전용 모달

  • tags taxonomy 페이지에서만 보이는 예시다.
  • 팝업처럼 닫을 수 있는 방식이 필요한 경우를 보여준다.
  • 특정 분류나 항목에만 안내를 붙이는 구조의 기준이 된다.

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

config/
└─ _default/
   ├─ hugo.toml
   └─ params.toml

themes/(0000-0000-0000-0001)/
├─ assets/
│  └─ css/
│     └─ core/
│        ├─ theme-vars.css
│        └─ theme-vars/
│           └─ 80-announcement.css
├─ i18n/
│  ├─ en.yaml
│  ├─ ko.yaml
│  ├─ jp.yaml
│  └─ cn.yaml
└─ layouts/
   ├─ _default/
   │  └─ baseof.html
   └─ partials/
      └─ theme/
         ├─ settings.html
         └─ announcement.html

운영 메모

  • 공지 기능 전체를 끄고 싶으면 config/_default/params.toml 의 [params.announcement].enabled 만 false 로 바꾸면 된다.
  • 문구만 바꿀 때는 themes/(0000-0000-0000-0001)/i18n/*.yaml 의 해당 키만 교체하면 된다.
  • 특정 섹션이나 분류에만 보이게 하려면 matchContentPrefixes, matchTaxonomies, matchTerms, matchKinds 를 조합하면 된다.
  • 새 언어를 추가할 때는 matchLangs 와 i18n 키만 같은 패턴으로 늘리면 된다.
  • 공지 디자인은 theme-vars 밖에서 조절하지 않는 것이 안전하다.

관련 원본 위치

  • 공지 정책: config/_default/params.toml
  • 공지 렌더러: themes/(0000-0000-0000-0001)/layouts/partials/theme/announcement.html
  • 공지 삽입 위치: themes/(0000-0000-0000-0001)/layouts/_default/baseof.html
  • 공지 텍스트: themes/(0000-0000-0000-0001)/i18n/*.yaml
  • 공지 디자인 토큰: themes/(0000-0000-0000-0001)/assets/css/core/theme-vars/80-announcement.css