제목은 자동으로 '앵커'가 됩니다

마크다운에서 제목(#, ## 등)을 쓰면, 많은 렌더러가 그 제목으로 이동할 수 있는 앵커(anchor)를 자동으로 만들어 줍니다. 이 앵커로 링크를 걸면 목차가 됩니다.

앵커 이름 규칙은 보통 이렇습니다.

  • 제목 글자를 소문자로
  • 공백은 하이픈(-)으로
  • 마침표·괄호·쉼표 등 특수문자는 제거
  • 한글은 그대로 유지

예를 들어 ## 설치 방법이라는 제목의 앵커는 #설치-방법이 됩니다.

몇 가지 예를 더 보겠습니다.

제목 앵커
## 설치 방법 #설치-방법
## Getting Started #getting-started
## API 레퍼런스 (v2) #api-레퍼런스-v2
## 자주 묻는 질문? #자주-묻는-질문

괄호와 물음표가 사라지고, 영문은 소문자로 내려가고, 공백만 하이픈으로 바뀌는 것을 볼 수 있습니다.

목차 직접 만들기

문서 맨 위에 목록을 만들고, 각 항목을 해당 제목의 앵커로 링크합니다.

## 목차

- [설치 방법](#설치-방법)
- [사용법](#사용법)
- [자주 묻는 질문](#자주-묻는-질문)

## 설치 방법
...

## 사용법
...

이제 목차 항목을 클릭하면 해당 섹션으로 바로 이동합니다.

하위 제목까지 넣고 싶다면 목록을 들여쓰면 됩니다.

- [설치 방법](#설치-방법)
  - [macOS](#macos)
  - [Windows](#windows)
- [사용법](#사용법)

⚠️ 같은 제목이 두 번 나오면

문서 안에 이름이 같은 제목이 여러 개 있으면 앵커가 겹칩니다. 이때 렌더러는 뒤에 나오는 것부터 번호를 붙입니다.

## 설치        → #설치
## 사용법
## 설치        → #설치-1

macOS와 Windows 아래에 각각 "설치"라는 소제목을 두는 식의 구조에서 자주 발생합니다. 목차를 만들었는데 두 항목이 같은 곳으로만 이동한다면 이게 원인입니다.

번호를 세어 #설치-1을 쓰는 방법도 있지만, 문서를 고치다 순서가 바뀌면 링크가 조용히 어긋납니다. 애초에 제목을 겹치지 않게 짓는 것이 안전합니다. "설치" 대신 "macOS에 설치", "Windows에 설치"처럼요.

⚠️ 이모지가 든 제목

README에서 흔한 ## 🚀 시작하기 같은 제목은 앵커가 예상과 달라집니다. 이모지는 앵커에서 제거되지만 그 자리의 공백이 하이픈으로 남아, 앞에 하이픈이 붙은 형태(#-시작하기)가 되는 경우가 많습니다.

규칙이 플랫폼마다 미묘하게 다르므로 추측하지 말고 실제 앵커를 확인하는 편이 빠릅니다. GitHub에서는 렌더된 문서의 제목에 마우스를 올리면 왼쪽에 사슬(🔗) 아이콘이 나타나는데, 이걸 클릭하면 주소창에 실제 앵커가 그대로 들어옵니다. 그 값을 복사해 쓰면 틀릴 일이 없습니다.

⚠️ 플랫폼마다 앵커 규칙이 다릅니다

목차를 만들 때 가장 크게 걸리는 지점입니다. GitHub에서 잘 되던 목차가 다른 곳에 옮기면 전부 먹통이 되는 일이 흔합니다.

앵커를 만드는 규칙이 표준으로 정해져 있지 않기 때문입니다. 렌더러마다 특수문자를 지우는 범위, 한글·유니코드 처리, 대소문자 변환, 중복 처리 방식이 조금씩 다릅니다. 어떤 도구는 아예 #section-1처럼 순번으로 앵커를 만들기도 합니다.

그래서 이렇게 대응하는 게 좋습니다.

  • 한 곳에서만 볼 문서라면 그 플랫폼 기준으로 만들고 확인
  • 여러 곳에 옮길 문서라면 목차를 자동 생성 기능에 맡기거나, 목차 없이 제목 구조만 잘 잡기
  • 옮긴 뒤에는 목차 링크를 반드시 한 번 눌러보기

특히 노션이나 티스토리로 붙여넣을 때는 앵커 링크가 그대로 살아남는 경우가 드뭅니다. 이런 플랫폼은 자체 목차 기능을 제공하니 그쪽을 쓰는 편이 낫습니다.

자동으로 만들어주는 곳도 많습니다

직접 만들 필요가 없는 경우가 생각보다 많습니다.

  • GitHub — 렌더된 .md 파일 상단에 목차 버튼이 있습니다. 제목 구조를 읽어 자동으로 만들어 주므로 README에 목차를 손으로 넣을 이유가 줄었습니다
  • 벨로그·노션 — 제목 구조를 분석해 옆에 목차를 띄워 줍니다
  • GitBook·Docusaurus·MkDocs — 빌드 시 목차를 생성합니다
  • markdown-toc, DocToc 같은 CLI 도구 — 문서를 읽어 목차 블록을 파일에 직접 써 넣습니다. 주석 마커 사이를 갱신하는 방식이라 문서가 바뀌어도 다시 돌리면 됩니다

환경에 자동 기능이 있다면 그걸 쓰는 게 낫습니다. 손으로 만든 목차는 문서를 고칠 때마다 같이 고쳐야 하고, 대부분 그걸 잊습니다.

목차를 넣어야 할 문서, 넣지 말아야 할 문서

목차는 있으면 무조건 좋은 게 아닙니다. 화면 첫 장을 목차가 다 차지하면 정작 본문이 안 보입니다.

넣으면 좋은 경우

  • 스크롤이 서너 번 이상 필요한 긴 문서
  • 처음부터 읽지 않고 필요한 부분만 찾아보는 문서 (API 문서, 레퍼런스, FAQ)
  • 제목이 5개 이상인 문서

넣지 않는 편이 나은 경우

  • 화면 한두 번에 다 들어오는 짧은 글
  • 처음부터 순서대로 읽어야 하는 글 (튜토리얼, 에세이)
  • 제목이 두세 개뿐인 문서

깊이도 마찬가지입니다. ##까지만 넣으면 한눈에 들어오지만, ####까지 전부 넣으면 목차 자체가 읽기 힘든 덩어리가 됩니다. ##와 ###까지가 대체로 적당합니다.

정리하면, 목차는 제목 → 앵커 → 링크 원리만 알면 어디서든 만들 수 있습니다. 다만 앵커 규칙이 플랫폼마다 다르니, 만든 뒤에는 실제로 눌러 확인하고, 자동 생성 기능이 있다면 그쪽에 맡기세요. 이지 마크다운 에디터에서 제목 구조를 잡고 마크다운으로 내보내 원하는 플랫폼에 옮기는 흐름이 편합니다.