NotionNext 문서

Appearance

ThoughtLite 테마 마이그레이션 작업 계획(NotionNext) ​

관련 요구사항: Issue #3987 · 새 테마 ThoughtLite

항목링크
업스트림 소스(Astro + Svelte + Tailwind)tuyuritio/astro-theme-thought-lite
온라인 미리보기thought-lite.ttio.workers.dev
이 저장소 작업 브랜치feat/theme-thoughtlite
현재 골격 디렉터리themes/thoughtlite/(themes/example에서 복사하고 설정 접두사를 바꾼 상태, 실행 가능하지만 최종 비주얼은 아님)

0. 라이선스와 규정 준수(먼저 확인 필수) ​

업스트림 저장소는 GPL-3.0입니다. NotionNext 메인 저장소는 MIT입니다.

  • 업스트림 .astro / .svelte 등의 소스를 이 저장소에 직접 복사하면 GPL과 MIT의 호환성 문제가 생길 수 있으므로, 병합 전 유지보수자가 전략을 확인해야 합니다. 예: 테마를 GPL 하위 디렉터리로 별도 설명하거나, GPL 텍스트를 복사하지 않고 “디자인 참고”만으로 React에서 재작성.
  • main에 병합하기 전 **PR 설명과 docs/developer/themes/THOUGHTLITE.md**에 라이선스 결론을 명시하세요.

1. Fuwari(Astro → Next) 마이그레이션과 같은 주의점 ​

docs/developer/themes/FUWARI.md와 테마 마이그레이션 가이드를 대조합니다.

  1. 기술 스택: 업스트림은 Astro + Svelte, NotionNext 테마는 Next.js Pages Router + React입니다. Astro 프로젝트를 “직접 마운트”할 수 없으며, 비주얼과 정보 구조를 이식해야 합니다.
  2. 데이터 계약: NotionNext가 전달하는 props(siteInfo, posts, post, customNav, customMenu, notice, tagOptions 등)만 사용합니다. 마이그레이션 가이드 §3 참고.
  3. 필수 연결 기능: 메뉴(CUSTOM_MENU 포함), 공지 NotionPage, 라이트/다크 useGlobal, 글 TOC/댓글/공유/저작권/이전·다음 글, 사이드바 위젯과 rightAreaSlot, 연락 이메일 handleEmailClick / resolveContactEmail 규칙(마이그레이션 가이드 §7).
  4. 설정: siteConfig('THOUGHTLITE_*', default, CONFIG)를 사용하고 themes/thoughtlite/config.js에 집중시켜 magic constant를 피합니다.
  5. 디렉터리 격리: 다른 테마 디렉터리의 컴포넌트를 참조하지 않습니다. 공통 기능은 @/components/*를 사용합니다.

2. 단계별 작업(권장 순서) ​

Phase A — 골격과 연동(현재 브랜치 목표) ​

  • [x] 새 브랜치 feat/theme-thoughtlite 생성.
  • [x] themes/thoughtlite 생성(example 골격 + THOUGHTLITE_* 설정 접두사 + id='theme-thoughtlite').
  • [x] 상단 바 / 푸터 / 홈 타임라인과 Latest 카드 / 글 카드화 초안(React 자체 스타일, 업스트림 Astro 소스 복사 아님).
  • [ ] 로컬 NEXT_PUBLIC_THEME=thoughtlite(또는 URL ?theme=thoughtlite)로 홈, 글, 아카이브, 카테고리, 태그, 검색, 404 동작 확인.
  • [ ] yarn lint / yarn type-check에서 이 테마 디렉터리로 인한 신규 오류 없음.

Phase B — ThoughtLite 레이아웃 정렬 ​

  • [ ] 업스트림 src/layouts, src/pages, 홈의 “타임라인 / Latest” 구조를 읽고 NotionNext 라우트(/, /[prefix]/[slug] 등)와의 매핑표 작성.
  • [x] 상단 내비게이션 교체: 사이트명 + 가로 메뉴 + 검색 진입점 + 라이트/다크 전환.
  • [x] 홈: publishDay별 타임라인 목록(스크롤/페이지네이션 모두 지원).
  • [x] 아카이브 페이지: 월별 그룹 목록과 홈과 일관된 타임라인 비주얼.
  • [x] 카테고리 / 태그 색인: tl-chip 내비게이션 블록.
  • [x] 검색 페이지: TlPageHero + 검색창 카드화; 키워드 하이라이트 useEffect 의존성 보완.
  • [ ] style.js: 업스트림 색상 팔레트, 간격, 폰트와 계속 정렬(현재는 첫 token 버전).

Phase C — 글과 사이드바 ​

  • [ ] 글 페이지: 본문 NotionPage, 커버, 메타 정보 밀도를 업스트림 글 페이지에 맞춤.
  • [ ] 사이드바/푸터: 필요에 따라 유지 또는 단순화; 통계, 광고, 플러그인 슬롯 연결(Fuwari 사이드바 모듈과 같은 방향).
  • [ ] 선택 사항: 업스트림 Swup류 전체 페이지 전환은 Next에서 비용이 크므로 framer-motion을 쓰거나 모션을 약하게 대체.

Phase D — 메인 저장소 등록 체크리스트 ​

  • [x] docs/developer/themes/THOUGHTLITE.md와 docs/developer/themes/THOUGHTLITE.en.md: 기능, 설정, 업스트림 감사와 라이선스 설명.
  • [x] docs/developer/themes/README.md / README.en.md 내비게이션 표 갱신.
  • [x] 테마 마이그레이션 가이드 §8에 따라 public/images/themes-preview/thoughtlite.png / .webp(현재는 플레이스홀더, 이후 실제 스크린샷으로 교체 가능)와 conf/themeSwitch.manifest.js 항목 제출.
  • [ ] PR 병합 시 유지보수자가 Closes #3987 여부 결정(여러 단계 요구사항이 남아 있으면 Issue 하위 작업으로 유지 가능).

3. 위험과 의존성 ​

위험완화
GPL / MIT§0 참고, PR 전 서면 결론 필요.
업스트림은 pnpm + Svelte, 이 저장소는 yarn + React라 불일치UI만 참고하고 패키지 매니저를 섞지 않음.
i18n전역 next.config locales와 일치; 업스트림 다국어 문구는 lib/lang 또는 테마 내부 사전으로 이전.
빌드 크기큰 의존성을 도입하지 않음; 아이콘은 기존 Iconify / Heroicons 체계를 우선 사용.

4. 검증 명령(개발 자체 점검) ​

bash
yarn dev
# 브라우저 접속: http://localhost:3000/?theme=thoughtlite

yarn build
yarn type-check

유지보수자는 Phase별로 체크하며 진행할 수 있습니다. 각 단계가 끝나면 리뷰하기 쉽도록 squash하거나 명확한 commit message를 남기는 것을 권장합니다.

5. 유지보수 문서 색인 ​

문서용도
THOUGHTLITE.md추가 이유, 업스트림 출처, 원작성자 저장소, 설정과 유지보수 체크리스트(주 진입점)
THOUGHTLITE.en.md위 내용의 영어판으로, 국제 기여자에게 유용
이 문서(마이그레이션 계획)단계별 작업, 위험, 검증 명령; 주 문서와 상호 참조