Markdown 목차 자동 생성기: 문서에 네비게이션을 바로 추가하는 법

길고 체계적인 README 파일을 작성하다 보면 어느 순간 목차가 필요하다는 걸 느끼게 됩니다. 그러면 제목 텍스트를 하나하나 소문자로 바꾸고, 공백을 하이픈으로 치환하고, 특수문자를 제거하면서 앵커 링크를 일일이 만들게 됩니다. 그러다 제목 하나가 바뀌면 링크도 수정해야 하고, 새 섹션이 추가되면 목차도 업데이트해야 하고... 결국 목차 관리가 하나의 부담이 됩니다.

이 과정은 사실 완전히 기계적인 작업입니다. GitHub-Flavored Markdown의 앵커 ID 생성 알고리즘은 명확하게 정의되어 있고, 사람이 직접 할 필요가 없습니다. Markdown 목차 생성기는 이 작업을 자동화합니다. Markdown 문서를 붙여넣으면 올바르게 들여쓰여진, 링크가 정확한 목차를 바로 얻을 수 있습니다.

목차가 왜 중요한가

목차는 단순한 장식이 아닙니다. 긴 문서에서 목차는 독자에게 문서의 전체 구조를 한눈에 보여주고, 원하는 섹션으로 바로 이동할 수 있게 해줍니다.

특히 GitHub README에서 이 효과가 큽니다. 처음 레포지터리를 방문한 개발자는 README를 훑어봅니다. 내용이 길고 목차가 없다면 프로젝트의 구조를 파악하는 데 불필요한 시간이 걸립니다. 잘 정리된 목차는 "이 프로젝트는 이렇게 구성되어 있습니다"를 즉각적으로 전달합니다.

기술 문서도 마찬가지입니다. API 레퍼런스, 아키텍처 가이드, 온보딩 문서 — 독자들은 처음부터 끝까지 읽지 않고 필요한 부분을 찾아서 봅니다. 목차는 그 길을 안내하는 지도입니다.

앵커 ID 생성 알고리즘 이해하기

GitHub이 제목 텍스트에서 앵커 ID를 만드는 방식은 간단합니다:

HTML 태그 제거
전체 텍스트 소문자 변환
하이픈과 공백을 제외한 특수문자 제거
공백을 하이픈으로 변환
중복 처리: 같은 제목이 두 번 이상 나오면 -1, -2 등을 붙임

예를 들어 ## API 레퍼런스 (v2)는 #api-레퍼런스-v2가 됩니다. ## 시작하기는 #시작하기가 됩니다.

한국어 제목의 경우 한글 자체는 앵커에 그대로 유지됩니다. URL에 퍼센트 인코딩된 형태로 보일 수 있지만 (%EC%8B%9C%EC%9E%91%ED%95%98%EA%B8%B0), 브라우저와 GitHub 모두 이를 올바르게 처리합니다.

중복 제목 처리

같은 이름의 섹션이 여러 개 있는 경우를 주의해야 합니다. 예를 들어 macOS, Linux, Windows 각각에 ### 설치 섹션이 있다면, 첫 번째는 #설치, 두 번째는 #설치-1, 세 번째는 #설치-2가 됩니다. 생성기는 이 중복 처리를 자동으로 수행합니다.

실제 예시

이런 구조의 문서가 있다고 가정해봅시다:

# 내 라이브러리

## 설치

### macOS

### Linux

## 빠른 시작

## API 레퍼런스

### 설정 옵션

### 메서드

## 기여 방법

## 라이선스

생성기를 통해 만들어지는 목차:

## 목차

- [설치](#설치)
  - [macOS](#macos)
  - [Linux](#linux)
- [빠른 시작](#빠른-시작)
- [API 레퍼런스](#api-레퍼런스)
  - [설정 옵션](#설정-옵션)
  - [메서드](#메서드)
- [기여 방법](#기여-방법)
- [라이선스](#라이선스)

H1 제목인 # 내 라이브러리는 목차에서 제외됩니다. H1은 문서 제목이지 내비게이션 대상이 아니기 때문입니다. 계층 구조도 그대로 반영됩니다 — H2는 최상위, H3은 한 단계 들여쓰기.

특수문자와 엣지 케이스

솔직하게 말하면, 일부 상황에서는 주의가 필요합니다.

제목에 이모지가 있는 경우 — ## 🚀 시작하기처럼 이모지가 포함된 제목은 렌더러마다 앵커 처리 방식이 다를 수 있습니다. GitHub에서는 이모지가 앵커에 포함되기도 하고 제거되기도 합니다. 이모지가 들어간 제목의 앵커 링크는 실제 플랫폼에서 직접 확인하는 게 좋습니다.

코드 스팬이 있는 제목 — ## `render()` 함수 같은 경우 백틱이 제거되어 #render-함수가 됩니다. 대부분의 경우 원하는 결과입니다.

괄호나 특수문자 — ## API 레퍼런스 (v2)에서 괄호는 제거되어 #api-레퍼런스-v2가 됩니다. 의도한 대로 동작하지만, 비슷한 이름의 섹션이 여러 개라면 앵커가 예상치 않은 형태가 될 수 있습니다.

워크플로우에 통합하기

일반적인 사용 흐름은 이렇습니다:

문서를 먼저 작성합니다 (목차 걱정 없이)
구조가 어느 정도 정해지면 Markdown을 목차 생성기에 붙여넣습니다
생성된 목차를 복사합니다
문서 상단 (소개 문단 뒤)에 붙여넣습니다

동기화 유지하기

이 도구의 한계는 문서가 변경되어도 목차가 자동으로 업데이트되지 않는다는 점입니다. 제목을 바꾸거나 섹션을 추가하면 목차를 다시 생성해서 교체해야 합니다.

소규모 프로젝트에서는 크게 문제없습니다. 하지만 문서가 자주 바뀌는 대형 프로젝트라면 자동화 도구를 고려해볼 수 있습니다:

doctoc: npm 패키지로, pre-commit 훅으로 설정하면 커밋 시 목차를 자동 갱신
VS Code 확장: Markdown TOC 관련 확장이 저장 시 자동 업데이트 지원
GitHub Actions: 푸시 시 doctoc을 실행하는 워크플로우 설정 가능

목차 생성기는 일회성 생성이나 출력을 확인하고 싶을 때 가장 이상적입니다.

함께 사용하면 좋은 도구들

Markdown 작업 흐름에서 함께 활용할 수 있는 도구들입니다.

Markdown 미리보기는 생성된 목차가 실제로 어떻게 보이는지 확인할 때 유용합니다. 제목 계층 구조와 목차의 들여쓰기가 올바른지 시각적으로 검증할 수 있습니다.

Markdown to HTML 변환기는 목차가 포함된 문서를 HTML로 변환해야 할 때, 예를 들어 CMS에 붙여넣거나 이메일 템플릿을 만들 때 필요합니다.

Markdown 테이블 생성기는 직접 작성하기 까다로운 파이프 구분 테이블 문법을 자동으로 만들어줍니다. 문서에 데이터 표가 필요하다면 시간을 크게 절약할 수 있습니다.

실무에서 알게 된 팁

제목 계층 구조를 먼저 정리하세요. H2와 H3을 무질서하게 섞어 쓰면 목차가 혼란스럽게 생성됩니다. 목차 생성 과정이 문서 구조의 문제를 드러내는 역할을 하기도 합니다.

평면적인 구조도 괜찮습니다. H2 제목만 있는 문서는 들여쓰기 없는 단순한 목차가 생성되는데, 이것이 오히려 더 깔끔할 때가 많습니다. 목차를 풍성하게 보이려고 불필요한 H3을 넣을 필요는 없습니다.

독자의 읽기 패턴을 고려하세요. 개발자가 반복해서 참조하는 API 레퍼런스라면 세부 계층까지 포함한 상세 목차가 도움이 됩니다. 처음 읽는 README라면 주요 섹션만 담은 간결한 목차로 충분합니다.

기계적인 작업을 자동화하면 실제 내용 작성에 집중할 수 있습니다. Markdown 목차 생성기를 다음 문서 작업에 활용해보세요.