마크다운 목차 생성기

목차가 실제로 바꾸는 것

목차의 효과는 흔히 부풀려서 이야기됩니다. 정직하게 정리하면 이렇습니다.

확실한 효과는 독자 쪽입니다. 긴 글에서 독자가 원하는 대목으로 바로 이동할 수 있으니 뒤로가기로 이탈하는 대신 그 문단을 읽습니다. 검색으로 들어온 사람이 첫 화면에서 "내가 찾던 내용이 이 안에 있구나"를 확인하는 장치이기도 합니다.

검색엔진 쪽 효과는 간접적입니다. 목차 자체가 순위 요소는 아닙니다. 다만 목차를 만들려면 헤딩을 제대로 달아야 하고, 헤딩 구조가 정리된 글은 검색엔진이 주제를 파악하기 쉬워집니다. 구글이 검색결과 아래에 붙이는 섹션 링크도 앵커가 있는 페이지에서 생기지만, 이건 구글이 알아서 판단하는 것이지 목차를 넣는다고 보장되지 않습니다.

앵커 링크가 동작하는 곳과 안 되는 곳

이 도구의 앵커 슬러그는 GitHub 방식입니다. 소문자로 바꾸고, 구두점을 지우고(한글·영숫자·공백·하이픈·밑줄만 남김), 공백을 하이픈으로 바꿉니다. 그래서 "## 고르는 기준"은 #고르는-기준 이 됩니다.

문제는 플랫폼마다 이 규칙이 다르다는 것입니다. 같은 제목이라도 워드프레스는 다른 슬러그를 만들고, 티스토리·네이버 블로그는 헤딩에 id를 자동으로 붙여주지 않습니다. 링크를 눌러도 아무 일이 안 일어난다면 규칙이 안 맞는 것입니다.

헤딩으로 안 잡히는 것들 — 의도된 동작입니다

"헤딩 개수"가 예상보다 적게 나온다면 대개 아래 규칙 때문입니다. 전부 오탐을 막기 위한 처리라 정상 동작입니다.

• 코드블록 안의 # — 백틱 세 개 또는 물결 세 개로 감싼 구간은 통째로 건너뜁니다. 셸 스크립트 주석(# 설치)이 H1으로 잡히는 사고를 막습니다.
• YAML 프론트매터 — 파일 맨 위 --- 로 둘러싼 구간은 무시합니다. Jekyll·Hugo 글을 그대로 넣어도 됩니다.
• # 뒤에 공백이 없는 줄 — #제목 은 헤딩이 아닙니다. 해시태그일 수 있으므로 마크다운 규칙대로 공백이 있어야 인식합니다.
• 표 안의 줄과 인용문(>) — 밑줄 스타일 헤딩 오인을 막기 위해 파이프(|)가 있는 줄, 목록·인용 줄은 제목 후보에서 제외합니다.
• 반대로 잡히는 것: 밑줄 스타일(Setext) 헤딩. 제목 아래 등호 줄은 H1, 하이픈 줄은 H2로 인식합니다.

깊이 설정과 목차 + 본문 모드

기본값이 H2부터 H3까지인 데는 이유가 있습니다. H1은 글 제목이라 목차에 넣으면 자기 자신을 가리키게 되고, H4 이하까지 넣으면 목차가 본문만큼 길어져 아무도 안 봅니다. 대부분의 블로그 글은 H2~H3 두 단계면 충분합니다.

"목차 + 본문" 모드는 목차를 본문 앞에 끼워 넣은 전체 마크다운을 출력합니다. 이때 맨 위 H1(글 제목)이 목차 범위 밖이면 그 H1 바로 아래에 목차를 넣습니다. 제목 위에 목차가 붙는 어색한 결과를 피하기 위해서입니다. "목차 제목" 칸에 값을 넣으면 목차 위에 ## 로 소제목이 붙고, 비우면 목록만 나옵니다.

1. 원문을 붙여넣고 헤딩 구조 표에서 회색(제외) 항목이 의도한 것인지 확인합니다.
2. 깊이를 H2~H3으로 두고 목차가 10~15줄 안쪽인지 봅니다. 넘치면 H2까지로 줄입니다.
3. 발행할 플랫폼이 앵커를 지원하지 않으면 "앵커 링크" 체크를 끕니다.
4. "목차 + 본문"으로 바꿔 전체를 복사하거나, 저장 버튼으로 with-toc.md 를 내려받습니다.