빠른 흐름

문서 outline 기준

1. H1은 문서 제목으로 1개만 둔다
2. 주요 장은 H2로 둔다
3. 세부 설명은 H3까지만 우선 사용한다
4. 같은 제목 반복을 피한다
5. 렌더러에서 자동 anchor를 확인한다

Outline 구조

목차는 heading 계층에서 나온다

Markdown 문서의 목차는 별도 데이터가 아니라 heading 계층에서 만들어지는 경우가 많다. GitHub는 두 개 이상의 heading이 있으면 파일 header의 Outline 메뉴에서 자동 목차를 제공한다. 정적 사이트 빌더도 대부분 heading을 읽어 sidebar, page TOC, anchor link를 만든다. 따라서 heading은 글자 크기 조절용이 아니라 문서 구조를 표현하는 도구로 써야 한다.

H1 프로젝트 이름

H2 설치
H3 요구 사항
H3 실행

H2 설정
H3 환경 변수
H3 권한

깊이를 많이 쓰면 탐색성이 떨어진다

H4, H5, H6까지 깊게 내려가면 자동 목차가 길어지고 모바일에서 읽기 어려워진다. 기술 문서에서는 H2와 H3로 대부분의 구조를 해결하고, 더 깊은 설명은 목록이나 표로 처리하는 편이 읽기 좋다. 섹션이 H4까지 계속 필요하다면 문서를 분리할 신호일 수 있다.

중복 제목은 anchor 충돌을 만든다

렌더러는 heading 텍스트를 기반으로 anchor를 만든다. 같은 문서에 동일한 제목이 여러 번 나오면 GitHub처럼 -1, -2를 붙이는 렌더러가 많지만, 이 규칙은 환경마다 다를 수 있다. "설치", "설정", "주의" 같은 제목이 반복될 때는 상위 맥락을 넣어 더 구체적으로 만드는 편이 안정적이다.

<!-- 모호함 -->
H2 설정
H2 설정

<!-- 더 안정적 -->
H2 로컬 설정
H2 배포 설정

수동 목차는 자동 생성 규칙과 같이 관리해야 한다

문서 상단에 수동 목차를 직접 작성하면 읽는 사람은 빠르게 이동할 수 있지만, heading을 바꿀 때 목차 링크도 함께 수정해야 한다. 자동 생성 TOC를 쓰는 환경에서는 수동 목차를 줄이고, 필요한 경우에는 CI나 문서 도구로 링크를 갱신하는 편이 낫다.

선택 기준

공식 참고: GitHub Docs: Basic writing and formatting syntax, CommonMark Spec

주의할 점

실패 예시
- H2 없이 H4로 세부 제목을 만들고, "주의" 제목을 여러 번 반복함
- 결과: 자동 목차가 읽기 어렵고 섹션 링크가 불안정해짐
- 대응: H2/H3 계층으로 재정리하고 제목에 맥락을 넣는다