본문 바로가기
자동 목차(TOC) 정확히 넣기｜H태그 계층·점프 링크·접근성 규칙
요약: 자동 목차는 제목만 많이 넣는다고 완성되지 않습니다. H태그 계층을 올바르게 잡고, 점프 링크가 고정 헤더에 가리지 않도록 scroll-margin-top을 지정하며, 키보드 포커스가 이동하도록 설계해야 진짜 탐색 도구가 됩니다.
서론｜자동 목차가 필요한 이유
자동 목차는 글의 구조를 한눈에 보여주고, 독자가 원하는 섹션으로 즉시 이동하게 합니다. 검색 스니펫 품질도 높아지며, 긴 글의 이탈을 줄입니다.
H태그 계층 규칙(좋은 예/나쁜 예) #
좋은 예
<h1>문서 제목(1회)</h1>
<h2 id="sec-setup">설치</h2>
<h3 id="sec-setup-req">사양 요구사항</h3>
<h3 id="sec-setup-step">설치 단계</h3>
<h2 id="sec-use">사용법</h2>
<h3 id="sec-use-basic">기본 기능</h3>
나쁜 예
<h1>제목</h1>
<h2>설치</h2>
<h4>사양 요구사항</h4> <!-- H3를 건너뜀 -->
<h2>사용법</h2>
<h2>사용법</h2> <!-- 동일 레벨 남발 -->
원칙: 레벨은 한 단계씩만 내려갑니다(H2→H3). 형제 섹션은 같은 레벨을 유지합니다.
점프 링크 구현｜아이디·앵커·스크롤 마진 #
<!-- 1) 제목에 고유 id 부여 -->
<h2 id="faq">FAQ</h2>
<!-- 2) 목차에서 해당 id로 링크 -->
<nav class="toc">
<ul><li><a href="#faq">FAQ</a></li></ul>
</nav>
<!-- 3) 고정 헤더 보정(스킨 CSS) -->
:target{ scroll-margin-top: 72px; }
주의: 동일한 id를 중복 사용하면 목차가 잘못 이동합니다. 짧고 고유한 영문-kebab-case를 권장합니다.
키보드 포커스 이동과 접근성 #
- 바로가기 링크: 최상단에 “본문 바로가기”를 두어 탭 한 번으로 콘텐츠에 진입.
- 포커스 표시: 링크·버튼은
:focus-visible로 시각적 테두리 제공. - 목차 역할:
<nav role="navigation">과aria-label로 보조기기에 맥락 제공.
<a class="skip" href="#main">본문 바로가기</a>
/* CSS */
:where(a,button):focus-visible{ outline:3px solid #22c55e; outline-offset:2px; }
예제 HTML 세트(복붙용) #
<!-- 자동 목차 블록 -->
<nav class="toc" aria-label="목차">
<strong>📑 목차</strong>
<ul>
<li><a href="#setup">설치</a></li>
<li><a href="#use">사용법</a></li>
<li><a href="#faq">FAQ</a></li>
</ul>
</nav>
<h2 id="setup">설치</h2>
<h3 id="setup-req">사양 요구사항</h3>
<h3 id="setup-step">설치 단계</h3>
<h2 id="use">사용법</h2>
<h3 id="use-basic">기본 기능</h3>
<h2 id="faq">FAQ</h2>
/* 고정 헤더 보정 */
:target{scroll-margin-top:72px;}
점검표｜흔한 실수와 합격 기준 #
| 항목 | 권장 규칙 | 합격 기준 |
|---|---|---|
| H계층 | H1(1회)→H2→H3 한 단계씩 | 레벨 건너뜀 없음 |
| 앵커 | id 고유·영문-kebab-case | 중복 id 0건 |
| 점프 | scroll-margin-top 지정 |
고정 헤더 가림 0건 |
| 포커스 | :focus-visible 표시 |
키보드만으로 탐색 가능 |
자주 틀리는 부분: H2 다음에 H4 사용, 목차에 외부 링크 섞기, 동일 id 재사용, 고정 헤더로 앵커 가림.
실천 요약 #
- 문서당 H1은 1회, 섹션은 H2, 하위는 H3로 고정.
- 목차 링크는 모두 고유 id로 연결,
scroll-margin-top으로 가림 방지. - “본문 바로가기”와
:focus-visible로 키보드 탐색 보장.