Markdown 목차 생성기

다섯 가지 앵커 스타일

앵커 스타일은 다섯 가지입니다. 쓰는 렌더러에 맞춰 고르세요.

• GitHub / Hugo: 소문자로 바꾸고, 문자·결합 부호·숫자·_·-·공백을 남기며, 공백 하나를 - 하나로 바꿉니다. 연속된 공백은 연속된 하이픈이 되고, 앞뒤 하이픈도 남습니다. github-slugger 2.0.0과 같은 규칙이며, 도구는 이것과 대조해 테스트합니다. Hugo의 Goldmark 렌더러는 기본값이 autoHeadingIDType: github입니다.
• GitLab: 같은 규칙입니다(GitLab 제목 앵커 문서, GitLab 17.0 이후). 연속된 하이픈을 합치지 않으므로 a --- b는 a-----b가 됩니다.
• Jekyll(kramdown GFM): Jekyll의 기본값은 input: GFM이며 kramdown-parser-gfm를 씁니다. GitHub처럼 Unicode를 남기고, 탭도 하이픈으로 바꾸며, 중복은 기본 이름별로 셉니다.
• kramdown(input: kramdown): kramdown 자체 파서(basic_generate_id)입니다. 첫 ASCII 영문자 앞의 문자를 지우고 a-z, 0-9, 공백, 하이픈만 남기며, 아무것도 남지 않으면 section을 씁니다.
• Bitbucket Cloud: 모든 앵커가 markdown-header-로 시작하고(Atlassian 이슈 BCLOUD-8276) 중복은 _N을 씁니다. 나머지 규칙은 공개되어 있지 않아 접두사 뒤에는 GitHub 규칙을 씁니다. Bitbucket Data Center는 제목에 id를 붙이지 않습니다.

마커 모드

마커 모드는 목차를 항상 최신으로 유지하면서, 문서의 나머지 부분은 건드리지 않습니다. 목차가 위치할 자리에 두 개의 HTML 주석을 미리 적어 두세요:

<!— toc —>
<!— /toc —>

이후 생성기를 실행할 때마다 두 주석 사이의 내용이 새로운 TOC로 교체됩니다. 아직 마커가 없다면 첫 제목 바로 앞에 새 마커 블록이 삽입되므로, 결과를 복사해 commit하기만 하면 됩니다.

예제

간단한 목차, GitHub 스타일

입력:

# API 레퍼런스

## 인증

### OAuth 흐름

## 엔드포인트

### GET /users
### POST /users

출력 (GitHub 앵커, 들여쓰기 공백 2칸):

- [API 레퍼런스](#api-레퍼런스)
  - [인증](#인증)
    - [OAuth 흐름](#oauth-흐름)
  - [엔드포인트](#엔드포인트)
    - [GET /users](#get-users)
    - [POST /users](#post-users)

중복된 제목

## 예제가 두 번 나오면 GitHub / GitLab / Jekyll에서는 #예제와 #예제-1, Bitbucket Cloud에서는 #markdown-header-예제와 #markdown-header-예제_1이 됩니다. kramdown 스타일에서는 한글이 지워져 #section과 #section-1이 됩니다.

H1 제외

정적 사이트가 frontmatter에서 H1을 렌더링한다면 H1 포함을 끄세요. TOC는 첫 H2부터 시작하고 들여쓰기가 한 단계씩 얕아집니다.

같은 문서, 다른 플랫폼

이 문서에는 중복된 ### Examples, 문장 부호, 한글 제목이 있습니다. 최소 레벨 2, 최대 레벨 3일 때:

# Install Guide
## Requirements
### Examples
## Usage
### Examples
## Q&A: what's new?
## 설치 (Install)

GitHub, GitLab, Jekyll(GFM)은 같은 목차를 만듭니다.

- [Requirements](#requirements)
- [Examples](#examples)
- [Usage](#usage)
- [Examples](#examples-1)
- [Q&A: what's new?](#qa-whats-new)
- [설치 (Install)](#설치-install)

kramdown 스타일에서는 설치가 지워지고 install만 남습니다.

- [Requirements](#requirements)
- [Examples](#examples)
- [Usage](#usage)
- [Examples](#examples-1)
- [Q&A: what's new?](#qa-whats-new)
- [설치 (Install)](#install)

Bitbucket Cloud는 GitHub과 같은 id 앞에 markdown-header-를 붙이고, 두 번째 Examples는 #markdown-header-examples_1이 됩니다.

제한

• ATX(#)와 setext(===, ---) 제목을 읽으며, HTML로 쓴 제목(<h2>)은 읽지 않습니다. 인라인 Markdown은 단순한 규칙으로 지우므로, 강조 안의 링크 같은 드문 구조에서는 목차 문구에 남는 기호가 있을 수 있습니다.
• 사용자 지정 id(kramdown과 Hugo의 ## 제목 {#custom-id})는 읽지 않고, 자동 생성 id를 계산합니다.
• 여기 없는 렌더러(VS Code 등)는 규칙이 다를 수 있습니다. 긴 목차를 커밋하기 전에 생성된 링크 하나를 열어 확인하세요.