NotionNext 사용 문서 유지보수 정책
유지보수 위치(공식 기준)
2026년부터 NotionNext 문서는 이 저장소의 docs/ 디렉터리를 주 유지보수 위치로 삼으며, Notion 호스팅에만 의존하던 온라인 매뉴얼(docs.tangly1024.com)을 점진적으로 대체합니다.
문서 사이트는 더 이상 “사이트 운영자 가이드”와 “개발자 문서”를 접근 경계로 나누지 않습니다. user-guide/는 배포, 설정, 테마 사용부터 다루고, developer/는 아키텍처, 기여, 테마 마이그레이션, 유지보수 의사결정을 이어서 다룹니다. AI 보조 개발로 테마 수정, 문제 해결, 문서 보강, PR 제출의 진입 장벽이 낮아진 만큼, 문서는 모든 사용자가 점차 기여자가 될 수 있도록 안내해야 합니다.
| 디렉터리 | 용도 |
|---|---|
docs/user-guide/ | 배포, 설정, Notion 데이터베이스, 메뉴, 업그레이드 등 사용자 가이드(공식 사이트에서 이전했으며 계속 갱신) |
docs/user-guide/reference/ | 4.9.x 참고 매뉴얼: 전체 사이트 설정 색인, Notion 신규 기능(conf/와 함께 유지보수) |
docs/user-guide/themes/THEMES_CATALOG.md | 25개 내장 테마 전체 표와 선택 가이드 |
docs/developer/ | 아키텍처, 기여 절차, 유지보수 매뉴얼, 테마 마이그레이션, RFC 등 심화 문서(온라인 사이트에 게시) |
docs/developer/themes/ | 테마 구현 상세 문서, 마이그레이션 계획, 업스트림 출처와 라이선스 설명 |
GitHub로 옮기는 이유
- 버전과 코드 동기화: 문서를
main브랜치와 릴리스 버전(예: 4.9.5.x)과 같은 저장소에서 관리해 “사이트 문서가 코드보다 뒤처지는” 문제를 줄입니다. - PR 리뷰 가능: 가이드 수정과 기능 변경을 같은 PR에서 논의할 수 있습니다.
- 정적 사이트 빌드 가능: Markdown을 VitePress / Nextra 등으로 빌드해 탐색 가능한 웹사이트로 만들 수 있습니다(계획은
user-guide/WEBSITE.md참고). - 오프라인 읽기 가능: 저장소만 클론하면 읽을 수 있으며, 문서 데이터베이스를 가져오기 위해 Notion API에 의존하지 않습니다.
온라인 문서와의 일관성
- 이전된 글의 끝에는 **「원문 링크」**를 남겨 docs.tangly1024.com의 대응 페이지를 가리키게 하며, 대조와 이미지 보강에 활용합니다.
- 전환 기간에는 공식 Notion 문서 데이터베이스도 계속 갱신될 수 있습니다. notionnext-org 메인라인의 권장 설명은 이 저장소
docs/user-guide/의 최신 커밋을 기준으로 합니다(fork는 필요에 따라 직접 동기화).
기여자가 문서를 수정하는 방법
작업 절차, 디렉터리 규칙, 체크리스트는 **사용자 문서 유지보수 워크플로**를 참고하세요(유지보수자 필독).
간단한 규칙:
- 사용 가이드 →
docs/user-guide/**/*.md를 편집하고user-guide디렉터리 색인과ARTICLE_INDEX.md를 함께 갱신합니다. - 테마 사용 설명 →
docs/user-guide/themes/<id>.md; 테마 구현, 마이그레이션, 유지보수 세부사항 →docs/developer/themes/; 양쪽은 서로 링크합니다. - 개인
.env나 비공개 ID를 예시에 넣지 않습니다. - PR 설명에 온라인 문서의 특정 글을 대체하거나 보완하는지 명시합니다(slug 또는 URL 포함).
마이그레이션 진행 상황
공식 도움말 매뉴얼의 핵심 섹션은 user-guide/로 이전되었습니다. 대응표는 user-guide/ARTICLE_INDEX.md, 상태는 user-guide/MIGRATION_STATUS.md를 참고하세요.
English summary
Documentation is maintained in this repo under docs/, as the long-term source of truth replacing Notion-only hosting at docs.tangly1024.com. User guides and developer docs are both published to the VitePress site so users can gradually become contributors. Migrated pages link back to the legacy site during transition.