Quick Reference

repo/
├─ README.md
├─ CHANGELOG.md
├─ docs/
│  ├─ index.md
│  ├─ setup.md
│  └─ images/
│     └─ architecture.png
└─ src/

README.md에는 시작에 필요한 판단과 다음 링크만 두고, 오래 읽는 설치·운영·API 설명은 docs/로 분리합니다. index.md, assets 경로, sidebar는 renderer와 repository convention에 따라 달라지므로, 파일을 옮길 때는 relative link와 publish 경로를 함께 검사합니다.

구조 기준

README는 모든 내용을 담는 문서가 아니라 길 안내 문서다

저장소의 README.md는 독자가 처음 보는 진입점입니다. 프로젝트가 무엇인지, 어떻게 시작하는지, 어디서 자세한 문서를 볼 수 있는지를 짧게 안내하는 역할이 큽니다. 설치, 운영, API, 아키텍처 설명이 길어지면 docs/로 분리하고 README에는 링크를 둡니다.

시작하기:

빠른 실행은 [설치 가이드](./docs/setup.md)를 참고하세요.
전체 문서는 [문서 인덱스](./docs/index.md)에서 볼 수 있습니다.

README에 모든 내용을 쌓으면 처음 읽는 속도는 느려지고, 문서 변경 시 링크와 목차를 유지하기 어려워집니다.

index 문서는 정적 사이트의 섹션 진입점으로 쓸 수 있다

문서가 여러 파일로 늘어나면 정적 사이트는 각 섹션의 index.md를 진입점이나 랜딩 페이지로 다루는 경우가 많습니다. GitHub repository에서 디렉터리 대표 문서를 자동으로 surface하는 이름은 README.md이므로, GitHub에서도 읽힐 구조라면 index.md에만 의존하지 말고 README 링크나 명시적 문서 목록을 둡니다.

docs/
├─ index.md
├─ guide/
│  ├─ index.md
│  ├─ install.md
│  └─ deploy.md
└─ api/
   ├─ index.md
   └─ auth.md

index.md는 세부 내용을 반복하기보다 어떤 문서를 먼저 읽을지, 어떤 순서로 이어지는지 보여 주는 데 집중합니다. 다만 이 이름이 route와 sidebar에서 어떤 역할을 하는지는 사용하는 사이트 도구의 convention을 따릅니다.

이미지 위치는 링크 수명과 함께 결정한다

이미지를 문서 옆에 둘지 공용 assets/에 둘지는 재사용 범위로 결정합니다. 특정 문서에서만 쓰는 이미지는 해당 문서 근처에 두면 이동 맥락이 명확합니다. 여러 문서가 공유하는 로고, 아키텍처 다이어그램, 공통 스크린샷은 공용 assets 경로가 낫습니다.

docs/setup.md
docs/images/setup-screen.png

docs/assets/logo.png
docs/assets/system-architecture.png

파일 이동이 잦은 프로젝트라면 문서와 이미지를 함께 이동할 수 있는 구조가 링크 유지에 유리합니다.

선택 기준

주의할 점

대소문자와 공백이 섞인 파일명은 플랫폼별 차이를 만듭니다. 공개 문서에서는 setup-guide.md, api-auth.md처럼 소문자와 hyphen 중심의 파일명을 쓰는 편이 안정적입니다.