ThoughtLite 테마(NotionNext)
English | 작업 계획: THOUGHTLITE_MIGRATION_PLAN.zh-CN.md
이 문서는 이 테마를 이후 유지보수할 개발자를 대상으로, 테마가 추가된 이유, 업스트림 출처, 원작성자 저장소, 규정 준수 주의사항, 일상 유지보수 포인트를 설명합니다.
1. 추가 배경과 이유
- 커뮤니티 제안: 사용자가 Issue #3987에서 새 테마 추가를 제안했습니다. 참고 대상은 오픈소스 Astro 테마 ThoughtLite이며, 읽기 중심 디자인, 타임라인형 홈, 가벼운 내비게이션이 NotionNext의 선택 가능한 스킨 중 하나로 적합하다고 보았습니다.
- 제품 목표: NotionNext의 기존 데이터 계약(
posts/post/customNav/ 댓글과 플러그인 등)을 깨지 않으면서, 비주얼과 정보 구조가 ThoughtLite에 가까운 React 테마를 제공해 사이트에서 한 번에 전환해 시험해 볼 수 있게 합니다.
2. 출처, 원작성자, 저장소
| 설명 | 링크 |
|---|---|
| 업스트림 테마명 | ThoughtLite(Astro 생태계) |
| 원작성자 GitHub | tuyuritio |
| 업스트림 소스 저장소 | tuyuritio/astro-theme-thought-lite |
| 업스트림 온라인 데모 | thought-lite.ttio.workers.dev |
| 업스트림 기술 스택 | Astro, Svelte, Tailwind CSS 등(업스트림 README 참고) |
| 업스트림 라이선스 | GPL-3.0 |
NotionNext 본 저장소의 주 라이선스는 MIT입니다. 이 테마 디렉터리의 구현은 업스트림의 “디자인 참고”를 바탕으로 Next.js + React에서 다시 작성한 것이며, 업스트림의 .astro / .svelte 같은 GPL 소스 텍스트를 직접 복사하지 않습니다. 향후 누군가 업스트림 컴포넌트 소스를 포함하려 한다면, 유지보수자가 GPL과 MIT의 호환성을 별도로 평가해야 합니다(마이그레이션 계획 §0 참고).
3. 이 저장소와의 대응 관계
| 차원 | 설명 |
|---|---|
| 테마 디렉터리 | themes/thoughtlite/ |
| 루트 노드 | #theme-thoughtlite(스타일과 전역 격리) |
| 설정 접두사 | THOUGHTLITE_*; themes/thoughtlite/config.js에 모아 두고 siteConfig('KEY', default, CONFIG)로 읽음 |
| 출발점 | 초기에는 themes/example 골격을 복사해 이름을 바꾸고, 이후 ThoughtLite 지향 UI로 점진적으로 교체 |
| 공통 로직 | 댓글, Notion 본문, 검색 등은 다른 테마와 마찬가지로 @/components/* 재사용 |
4. 기능 개요(유지보수 시 대조)
- 상단 바: 사이트 제목, 가로 내비게이션(커스텀 메뉴 포함), 검색 진입점, 라이트/다크 전환(
components/Header.js,MenuList.js,MenuItemDrop.js). - 홈: 선택 가능한 Latest 카드, **
publishDay**별 타임라인 목록(HomeTimeline.js,BlogItem의timeline변형); 페이지네이션 / 스크롤 목록 두 가지 전역POST_LIST_STYLE지원. - 글 페이지: 카드형 제목 영역,
PostMeta,NotionPage,ShareBar, 댓글 영역(dynamic으로 SSR 비활성화), 사이드바 TOC 등(index.js의LayoutSlug). - 아카이브 / 카테고리 / 태그 / 검색: 통합
TlPageHero페이지 헤더; 아카이브는 타임라인 레일; 카테고리와 태그는tl-chip(style.js). - 푸터: 저작권, ICP 등록 정보,
PoweredBy, 그리고 ThoughtLite 테마명 + 업스트림 저장소와 원작성자 링크(components/Footer.js). - 테마 전환:
conf/themeSwitch.manifest.js의thoughtlite항목; 미리보기 이미지public/images/themes-preview/thoughtlite.{png,webp}(현재는 플레이스홀더 가능, 출시 전 실제 스크린샷으로 교체하고yarn perf:compress-theme-previews실행 권장).
5. 설정 항목 개요(themes/thoughtlite/config.js)
| 키 | 의미 |
|---|---|
THOUGHTLITE_MENU_CATEGORY / TAG / ARCHIVE / SEARCH | 상단 바에 해당 메뉴 항목을 표시할지 여부 |
THOUGHTLITE_HOME_TIMELINE | 순수 홈에서 일자별 타임라인을 사용할지 여부 |
THOUGHTLITE_HOME_LATEST_CARD | 홈에 Latest 요약 블록을 표시할지 여부 |
THOUGHTLITE_SIDEBAR_ONLY_ON_POST | 글 상세 페이지에서만 사이드바를 표시할지 여부 |
THOUGHTLITE_POST_LIST_COVER | 목록에 커버를 표시할지 여부(타임라인 시나리오에서는 false 권장) |
THOUGHTLITE_TITLE_IMAGE | 글이 아닌 페이지의 TitleBar에 큰 배경 이미지를 사용할지 여부 |
THOUGHTLITE_HOME_MINIMAL_HEADER | 홈에서 큰 TitleBar를 숨길지 여부 |
THOUGHTLITE_ARTICLE_LAYOUT_VERTICAL | 글 페이지의 본문 영역과 사이드바를 위아래 스택으로 바꿀지 여부 |
THOUGHTLITE_ARTICLE_HIDDEN_NOTIFICATION | 글 페이지에서 공지를 숨길지 여부 |
전역 항목 **LAYOUT_SIDEBAR_REVERSE**는 여전히 사이트 수준 설정이 제어하며, 이 테마의 LayoutBase와 함께 작동합니다.
6. 활성화 방법
# .env.local 또는 배포 환경
NEXT_PUBLIC_THEME=thoughtlite로컬 개발: yarn dev 후 사이트에 접속합니다. 테마 전환을 지원하는 상황에서는 URL 파라미터 ?theme=thoughtlite로 시험할 수도 있습니다(실제 라우트와 설정 기준).
7. 마이그레이션과 유지보수 사항(후속 개발자용)
- 스타일 변경 우선 위치는
themes/thoughtlite/style.js의#theme-thoughtlite아래 CSS 변수와 클래스명입니다. 다른 테마를 오염시키지 않도록 합니다. - 레이아웃과 라우트 변경은
themes/thoughtlite/index.js의 각Layout*를 진입점으로 삼습니다. 목록 하위 컴포넌트는themes/thoughtlite/components/에 있습니다. - 업스트림 비주얼 정렬 시에는 업스트림 데모 사이트와 공개 UI 동작만 대조하는 것을 권장하며, 업스트림 GPL 소스의 전체 파일 복사는 피합니다. 긴 코드 인용은 PR에서 규정 준수 경로를 설명해야 합니다.
- 데이터 필드: 타임라인은
post.publishDay,post.publishDate에 의존합니다(Notion 속성 매핑에서 생성,lib/db/notion/getPageProperties.js참고). Notion 내부 ID를 하드코딩하지 마세요. - 다른 테마와 동작을 맞출 때는 FUWARI.md와 테마 마이그레이션 가이드의 메뉴, 댓글, TOC, 플러그인 슬롯 규칙을 참고할 수 있습니다.
- 테마 전환 미리보기 갱신 시
public/images/themes-preview/thoughtlite.png를 교체하고, 저장소가 해당 스크립트를 유지한다면yarn perf:compress-theme-previews를 실행해 webp를 갱신합니다. - 병합 전 자체 점검:
yarn lint --dir themes/thoughtlite,NEXT_PUBLIC_THEME=thoughtlite상태에서 주요 라우트(홈, 글, 아카이브, 카테고리, 태그, 검색, 404, 암호 글)를 수동으로 확인합니다.
더 자세한 단계별 체크리스트는 THOUGHTLITE_MIGRATION_PLAN.zh-CN.md를 참고하세요.
8. 관련 링크 모음
- 요구사항: notionnext-org/NotionNext#3987
- 업스트림 저장소: tuyuritio/astro-theme-thought-lite
- 업스트림 데모: thought-lite.ttio.workers.dev
9. 현재 단계 설명(리뷰어와 기여자용)
이 테마는 초기 병합 가능한 구현입니다. 핵심 목록과 글 흐름은 연결되어 있지만, 비주얼과 인터랙션은 여전히 반복적으로 개선될 예정입니다(색상 팔레트, 간격, 모션, 접근성, 다른 플러그인과의 세부 호환성 등). PR 병합이 Issue의 모든 “픽셀 단위 업스트림 정렬” 요구가 완료되었다는 뜻은 아닙니다. 이후 같은 테마 디렉터리 안에서 작은 PR로 계속 발전시킬 수 있습니다.