사용자 문서 유지보수 워크플로
사이트 관리자, 기여자, 유지보수자를 위한 문서입니다. 저장소 안에서 NotionNext 사용 설명을 올바르게 추가, 수정, 정렬하는 방법을 설명합니다.
전체 전략: DOCUMENTATION_POLICY.md
독자 안내: 사용 설명서 목차 · 공식 slug 대조표: ARTICLE_INDEX.md
1. 유지보수자가 먼저 기억할 세 가지
- 권위 있는 위치: 사이트 관리자용 튜토리얼은
docs/user-guide/에 둡니다. 테마는user-guide/themes/<id>.md로 통일합니다.docs/developer/themes/에는 개발자용 심화 문서만 둡니다. - 세 곳을 함께 동기화: 튜토리얼을 수정할 때는 상황에 따라 본문, README 목차, ARTICLE_INDEX를 함께 갱신합니다. 새로 만들거나 폐기할 때는 MIGRATION_STATUS도 수정합니다.
- 코드와 일치: 환경 변수명, 설정 키, 기본값은
conf/*.config.js,blog.config.js, 각 테마의themes/*/config.js를 기준으로 합니다. 버전 번호는package.json을 기준으로 합니다.
2. 문서를 어디에 둘지, 디렉터리 질서
| 작성하려는 내용 | 디렉터리 | 파일명 관례 |
|---|---|---|
| 사이트 구축 소개, 전체 흐름 | docs/user-guide/ 루트 | intro.md, deploy-vercel.md 같은 짧은 이름 |
| 배포 / 도메인 / 플랫폼 | docs/user-guide/deploy/ | 플랫폼 또는 주제.md, 예: netlify.md |
| 사이트 설정, URL, 검색 | docs/user-guide/config/ | 기능명, 예: url-customize.md |
| Notion 사용 팁 | docs/user-guide/notion/ | |
| 버전과 업데이트 설명 | docs/user-guide/changelog/ | |
| 테마, 사이트 관리자용 | docs/user-guide/themes/<id>.md | 25편. generate-theme-user-docs.mjs로 설정 표를 갱신합니다. Proxio/Heo는 병합 주제를 포함합니다. |
| 테마, 개발자용 | docs/developer/themes/ | Claude, Endspace처럼 전역 변경이 있는 긴 문서만 둡니다. 사이트 관리자 문서와 중복하지 않습니다. |
| 4.9.x 설정 / Notion 기능 | docs/user-guide/reference/ | features.md, notion-4x.md. conf/ 수정 후 반드시 동기화합니다. |
| 통계 / 댓글 / 위젯 | analytics/, comments/, plugins/ | 플러그인 하나당 한 문서 또는 총람 |
| 개발, 아키텍처 | docs/user-guide/development/ + docs/developer/GETTING_STARTED.md 등 | 사용자용은 짧게 쓰고 세부 내용은 docs/에 둡니다. |
| 운영, SEO | docs/user-guide/operations/ | |
| 커뮤니티, 피드백, 후원 | docs/user-guide/help/ |
사이트 관리자 튜토리얼을 docs/developer/ARCHITECTURE.md에 쓰지 마세요. 아키텍처 세부 내용을 user-guide에 길게 넣지 마세요. 필요한 경우 짧게 설명하고 docs/developer/로 링크합니다.
3. 독자 읽기 순서, 유지보수 시 흐트러뜨리지 않기
README.md의 빠른 시작 1->6단계가 권장 경로입니다. 새 총람 문서를 추가할 때는 정말 입문 필수 단계가 아니라면 이 6단계 사이에 끼워 넣지 마세요.
권장 독자 경로:
text
intro -> deploy-vercel -> notion-database -> config-site -> menu-secondary -> update섹션 내부 순서, README.md의 각 소제목, 는 다음을 유지하는 것을 권장합니다.
text
배포 -> Notion -> 설정 확장 -> 테마 -> 통계/댓글/플러그인 -> 개발/운영 -> 도움말 -> 업데이트 로그4. 표준 워크플로, 상황별
상황 A: 오타 수정 / 단계 업데이트, 작은 변경
mermaid
flowchart LR
A[해당 .md 편집] --> B{제목이나 경로를 바꿨는가?}
B -->|아니오| C[PR 제출]
B -->|예| D[README + ARTICLE_INDEX 업데이트]
D --> C- ARTICLE_INDEX.md에서 로컬 경로를 찾습니다.
- 본문을 수정합니다. 문서에 원래 있던
> 이전 원문:과 문서 끝의 원문 링크는 출처와 계속 대응된다면 유지합니다. yarn실행은 필요 없습니다. 문서 PR의 commit 메시지는docs(user-guide): 설명형식을 권장합니다.- PR 설명에는 무엇을 바꿨는지, 현재
main설정과 일치하는지 적습니다.
상황 B: 사이트 관리자 튜토리얼 새로 추가
- 디렉터리 결정: 2절에 따라 하위 디렉터리를 고릅니다. 파일명은 소문자 영어 + 하이픈을 사용합니다. 예:
deploy/xxx.md. - 본문 템플릿 작성, 복사한 뒤 채웁니다.
markdown
# 제목
> 이전 원문: [원문 제목](https://docs.tangly1024.com/article/slug) · 마지막 동기화: YYYY-MM
본문: 단계는 순서 있는 목록, 설정은 표, 명령은 코드 블록 사용
## 관련
- 이 저장소의 다른 문서로 연결
## 원문 링크
https://docs.tangly1024.com/article/slug- 내비게이션 업데이트, 필수
- 사용 설명서 목차: 해당 섹션에 링크를 추가합니다.
- ARTICLE_INDEX.md:
slug | 로컬 경로행을 추가합니다. - MIGRATION_STATUS.md: "마이그레이션 대기"에서 완료로 바뀌었다면 상태 표를 수정합니다.
- 교차 참조: 환경 변수를 다룬다면 본문에
NEXT_PUBLIC_*와conf/*.config.js의 키 이름을 명시합니다. - PR 제출: 제목은
docs(user-guide): add <topic>을 권장합니다. 기존 문서 사이트의 slug와 대응되는지도 적습니다.
상황 C: 코드에 설정 항목 / 기능 추가
기능 PR과 같은 PR 또는 바로 이어지는 docs PR에서 처리합니다.
conf/*.config.js에 주석을 추가할 때는docs/user-guide/... 참고처럼 적을 수 있습니다.user-guide에서 해당 플러그인/설정 문서를 업데이트합니다. 필요하면config-site.md/config/site-basics.md도 수정합니다.- 업그레이드 경로에 영향이 있다면 update.md 또는 changelog/latest.md를 함께 갱신합니다.
- breaking change는 changelog와 문서에서 눈에 띄게 표시해야 합니다.
상황 D: 테마 신규 추가 또는 테마 설정 대규모 변경
- 사이트 관리자용:
docs/user-guide/themes/<id>.md에서 유지보수합니다.node scripts/generate-theme-user-docs.mjs를 실행해 설정 표를 갱신합니다. - 테마가 전역 파일 / 아키텍처를 건드릴 때만
docs/developer/themes/에 개발자 문서를 보강하고,<id>.md에 "개발자 심화 문서" 링크를 추가합니다. 사이트 관리자 본문을 반복하지 마세요. - themes/overview.md의 테마 목록을 갱신합니다.
themes/디렉터리의 실제 폴더와 일치해야 합니다. - ARTICLE_INDEX.md를 갱신합니다.
상황 E: 폐기 또는 외부 링크만 유지
- 본문 상단에
> 폐기됨: ...을 사용하세요같은 설명을 추가합니다. - 파일을 삭제할 때 죽은 링크가 남지 않도록 저장소 전체에서 해당 파일 경로를 검색합니다.
ARTICLE_INDEX를 "원문 사이트만 링크" 영역으로 옮기거나 행을 삭제하고 이유를 적습니다.README에서는 제거하거나 "보관됨, xxx 참고"로 바꿉니다.
5. 제출 전 확인 목록
PR 설명이나 자체 점검에 복사해 사용할 수 있습니다.
markdown
- [ ] 경로가 docs/user-guide/ 디렉터리 규약을 따름
- [ ] README.md 링크를 추가/조정함
- [ ] ARTICLE_INDEX.md를 업데이트함, 새 slug / 새 경로
- [ ] .env, Token, 개인 도메인 ID, 실제 API Key 예시가 없음
- [ ] 환경 변수명이 conf/*.config.js와 일치함
- [ ] 버전 번호가 package.json / Releases와 일치함, 버전을 언급했다면
- [ ] tangly1024 문서 사이트에서 온 문서라면 원문 링크를 유지하거나 업데이트함
- [ ] 사이트 내 상대 링크를 클릭할 수 있음, `./` 또는 `../`
- [ ] 개발자용 긴 문서를 user-guide에 반복 붙여넣지 않음6. 주의 사항, 자주 하는 실수
콘텐츠와 보안
| 금지 | 권장 |
|---|---|
실제 NOTION_PAGE_ID, Token, 비밀 키 제출 | your-xxx, example 사용 |
| 이미 만료된 서드파티 URL을 고정해 작성 | 공식 문서로 연결하고, 단계는 "콘솔 기준"이라고 작성 |
main 브랜치 설정 키와 불일치 | 문서 수정 전 해당 conf/*.config.js 확인 |
구조와 링크
- 한 문서, 한 주제: 댓글 플러그인은
comments/에 분리합니다. 총람 + 하위 링크 문서가 아니라면 모두 한 문서에 쌓지 않습니다. - 총람 + 개별 문서:
overview.md는 비교 표와 링크만 쓰고, 세부 내용은 하위 페이지에 둡니다. - 테마 본문 반복 금지: 각 테마는 사이트 관리자 문서
user-guide/themes/<id>.md하나만 유지합니다.docs/developer/themes/PROXIO.md,HEO.md는 리디렉션 stub만 둡니다. - changelog: 긴 과거 기록은 changelog/v4-history.md + GitHub Releases에 둡니다.
user-guide루트에 수천 줄 로그를 붙이지 마세요.
기존 문서 사이트와의 관계
- 전환 기간에는 원문 링크를 유지해 스크린샷과 비교하기 쉽게 합니다.
- 기준은 이 저장소입니다. 원문 사이트와 충돌하면 이 저장소의
main+ 현재 코드를 기준으로 하고 PR에 설명합니다. - 해당 문서가 저장소 고유 문서가 되어 원문 사이트와 무관해진 경우가 아니라면 "이전 원문" 행을 일괄 삭제하지 마세요.
PR과 협업
- 문서 전용 브랜치:
docs/xxx또는docs/user-guide-xxx. - 문서와 기능을 별도 PR로 나누면 기능 PR에
Docs follow-up: #xxx를 적습니다. - CONTRIBUTION_WORKFLOW.md, GitHub를 따릅니다. lint/test는 순수 문서 PR에서 선택 사항이지만, 관련 없는 파일은 수정하지 마세요.
7. 게시와 후속 작업, 선택 사항
- 정적 사이트 계획은 WEBSITE.md를 참고하세요. VitePress / Nextra.
- 릴리스 시: changelog/latest.md가 현재
package.jsonversion을 가리키는지 확인합니다. - Fork 사용자: README가 이미
docs/user-guide/를 가리키므로 upstream을 병합하면 문서 업데이트를 받을 수 있습니다.
8. 1분 결정표
| 하고 싶은 일 | 할 일 |
|---|---|
| 배포 단계 수정 | deploy/*.md + README |
| 댓글/통계 설정 설명 수정 | comments/ 또는 analytics/ + conf/ 확인 |
| Proxio 상단 바 수정 | docs/user-guide/themes/proxio.md |
| 개발 환경 수정 | docs/developer/GETTING_STARTED.md, user-guide에는 링크만 유지 |
| 어디에 쓸지 모름 | ARTICLE_INDEX.md 확인 |
| 새 기능에 문서 없음 | 상황 B + C |
English summary
Maintain end-user docs under docs/user-guide/. On every add/change: update the article, README.md, and ARTICLE_INDEX.md. Match env var names to conf/*.config.js. Never commit secrets. Use the checklists in Section 5 before opening a PR.