인덱스 운영 규칙¶
index.md는 위키의 수동 카탈로그이지만, wiki/ 문서의 frontmatter를 기준으로 일관되게 유지합니다.
1. 섹션 매핑 규칙¶
type: source문서는소스섹션에 넣습니다.type: entity문서는엔티티섹션에 넣습니다.type: concept문서는개념섹션에 넣습니다.type: comparison문서는비교 및 분석섹션에 넣습니다.type: synthesis문서는합성 문서섹션에 넣습니다.type: template문서는템플릿섹션에 넣습니다.type: guide문서는 기본적으로개요섹션에서 안내 문서로 다룹니다.
2. 정렬 규칙¶
개요섹션은 수동 큐레이션입니다. 자주 참조하는 핵심 문서만 유지합니다.소스,엔티티,개념,비교 및 분석,합성 문서,템플릿섹션은title기준 가나다/알파벳 순으로 정렬합니다.- 같은 유형 문서가 늘어나도 날짜순보다 제목순 정렬을 우선합니다.
3. 항목 작성 규칙¶
- 링크 텍스트는 가능하면 frontmatter의
title과 맞춥니다. - 설명은 한 문장으로 짧게 작성합니다.
- 파일이 존재하더라도 내용상 미완성이라면
index.md에 올리기 전에 최소 설명 가능 상태인지 확인합니다.
4. 갱신 규칙¶
- 새
wiki/문서를 만들면 같은 변경에서index.md를 갱신합니다. - 문서의
type이나title이 바뀌면index.md위치와 링크 텍스트도 같이 바꿉니다. updated는 문서 내부 변경 시 갱신하고,index.md는 그 변경을 반영하는 카탈로그로 취급합니다.
5. 제외 규칙¶
raw/문서는 기본적으로index.md의 주요 콘텐츠 섹션에 넣지 않습니다.- 예외적으로 참고가 필요한 샘플 입력이나 실전 ingest 입력만
템플릿또는개요근처에 안내용으로 노출할 수 있습니다.
6. 권장 점검¶
- 새 페이지 추가 후
docs/lint-checklist.md의 구조 점검 항목을 함께 확인합니다. - frontmatter와
index.md항목이 어긋나면 frontmatter를 기준으로 맞춥니다.
7. 초안 생성 명령¶
자동 관리 섹션 초안이 필요하면 아래 명령을 실행합니다.
python3 scripts/generate_index_draft.py
이 스크립트는 소스, 엔티티, 개념, 비교 및 분석, 합성 문서, 템플릿 섹션 초안만 생성합니다. 개요 섹션과 설명 문구는 계속 수동 큐레이션으로 유지합니다.
8. 동기화 검사 명령¶
현재 index.md가 wiki/ frontmatter와 맞는지 확인하려면 아래 명령을 실행합니다.
python3 scripts/check_index_sync.py
이 명령은 index.md의 관리 대상 링크와 frontmatter 기반 기대값을 비교합니다. 어긋나면 종료 코드 1로 실패합니다.
9. 통합 검증 명령¶
기본 위키 검증을 한 번에 실행하려면 아래 명령을 사용합니다.
python3 scripts/verify_wiki.py
이 명령은 현재 두 가지를 검사합니다.
wiki/문서에 frontmatter가 있는지- Markdown 상대 경로 링크가 실제 파일을 가리키는지
type: source문서의raw_source가 실제 raw 파일을 가리키는지index.md관리 섹션이wiki/frontmatter와 동기화되어 있는지