제목 ID

제목 ID는 Markdown의 확장 기능으로, 제목에 사용자 정의 식별자를 추가하여 정확한 링크 생성과 문서 구조 제어를 용이하게 합니다.

기본 문법

제목 ID 추가

제목 ID는 중괄호 문법을 사용하며, 제목 텍스트 뒤에 배치됩니다:

## 내 제목 {#사용자-정의-id}

렌더링 효과:

HTML 출력은 제목 요소에 이 사용자 정의 ID를 추가합니다:

<h2 id="사용자-정의-id">내 제목</h2>

다단계 제목 ID

모든 수준의 제목에 사용자 정의 ID를 추가할 수 있습니다:

# 1단계 제목 {#1단계}

## 2단계 제목 {#2단계}

### 3단계 제목 {#3단계}

#### 4단계 제목 {#4단계}

적용 시나리오

앵커 링크 생성

사용자 정의 ID를 사용하여 문서 내 특정 부분을 가리키는 링크를 생성할 수 있습니다:

[내 제목으로 이동하려면 클릭](#사용자-정의-id)

...다른 내용...

## 내 제목 {#사용자-정의-id}

렌더링 효과:

링크를 클릭하면 사용자-정의-id가 있는 제목으로 직접 이동합니다.

문서 특정 섹션에 대한 외부 링크

사용자 정의 ID는 외부 문서에서 특정 내용으로의 링킹도 용이하게 합니다:

[다른 문서의 특정 섹션으로 링크](other-doc.html#특정-섹션)

URL을 통한 특정 섹션 공유

ID가 있는 제목은 URL을 통해 다른 사람과 공유하여 문서의 특정 섹션을 가리킬 수 있습니다:

https://www.markdownlang.com/documentation.html#설치-가이드

고급 사용법

다단어 제목 ID

제목에 여러 단어가 포함된 경우, 제목 ID는 일반적으로 하이픈을 사용하여 연결합니다:

## 설치 및 구성 가이드 {#설치-및-구성}

목차 생성과 제목 ID

많은 Markdown 프로세서가 제목 내용을 기반으로 자동으로 ID를 생성합니다. 사용자 정의 ID를 통해 제목 내용 변경에 영향을 받지 않는 안정적인 목차 링크를 보장할 수 있습니다:

## 시작하기 가이드 {#시작하기}

나중에 제목을 "시작하기"로 변경해도 ID가 동일하게 유지되므로 링크가 유효합니다.

국제화 및 비영어 문자

비영어 제목의 경우, 사용자 정의 ID는 안정적인 영어 식별자를 제공하므로 특히 유용합니다:

## 설치 지침 {#installation}

## 사용 가이드 {#usage}

## 자주 묻는 질문 {#faq}

호환성 및 구현 차이

다양한 플랫폼의 지원 상태

플랫폼/도구	제목 ID 지원	문법
GitHub Markdown	✅	{#id}
GitLab Markdown	✅	{#id}
Jekyll (kramdown)	✅	{:#id} 또는 {#id}
Hugo	✅	{#id}
CommonMark	❌	지원하지 않음
VitePress	✅	{#id}
Pandoc	✅	{#id}

자동 ID 생성 규칙

사용자 정의 ID가 제공되지 않으면 대부분의 Markdown 프로세서가 제목 텍스트에서 자동으로 ID를 생성합니다:

1. 소문자로 변환
2. 특수 문자 제거 또는 대체
3. 공백을 하이픈으로 대체
4. 중복 하이픈 제거
5. ID 고유성 보장 (보통 숫자 접미사 추가)

예시:

제목	자동 생성된 ID
## 시작하기	#시작하기
## FAQ & 도움말	#faq-도움말
## 빠른 시작	#빠른-시작 또는 #section-1 (플랫폼별로 다름)

모범 사례

제목 ID 명명 규칙

✅ 권장 사례:

1. **간결하고 설명적인 ID 사용**:
   - `{#설치}`
   - `{#api-참조}`
   - `{#문제해결}`

2. **일관된 명명 스타일 유지**:
   - 모두 소문자
   - 단어 구분에 하이픈 사용
   - 밑줄이나 camelCase 피하기

3. **ID 안정성 유지**:
   - ID 변경 빈도 최소화
   - 제목 텍스트 수정 시 원래 ID 보존

❌ 피해야 할 사례:

1. 특수 문자 사용 (예: `!@#$%^&*()`)
2. 설명적이지 않은 ID 사용 (예: `{#section1}`)
3. 너무 긴 ID 생성
4. 공백이나 문장 부호 사용

문서 구조와 제목 ID

대용량 문서의 경우, 탐색을 용이하게 하기 위해 주요 장에 표준화된 ID를 사용하는 것이 권장됩니다:

# 제품 문서 {#제품-문서}

## 소개 {#소개}

## 설치 {#설치}

### Windows 설치 {#설치-windows}

### macOS 설치 {#설치-macos}

### Linux 설치 {#설치-linux}

## 구성 {#구성}

## API 참조 {#api-참조}

## FAQ {#faq}

실제 적용 예시

기술 문서의 제목 ID

기술 문서의 제목 ID는 사용자가 특정 섹션에 직접 링크할 수 있도록 도와줍니다:

# API 문서 {#api-문서}

## 인증 {#인증}

### API 키 얻기 {#api-키-얻기}

### OAuth 인증 {#oauth}

## 엔드포인트 {#엔드포인트}

### 사용자 엔드포인트 {#엔드포인트-사용자}

### 제품 엔드포인트 {#엔드포인트-제품}

학술 논문의 제목 ID

학술 논문은 제목 ID를 사용하여 인용과 상호 참조를 생성할 수 있습니다:

# 연구 방법론 {#방법론}

[연구 결과](#결과)에서 보여주듯이, 우리의 방법은 여러 테스트 케이스에서 잘 작동합니다.

...

# 연구 결과 {#결과}

이 섹션은 [연구 방법론](#방법론)에서 설명한 실험 결과를 제시합니다.

일반적인 문제 해결

제목 ID가 작동하지 않음

제목 ID가 작동하지 않는 경우:

1. 플랫폼이 사용자 정의 제목 ID를 지원하는지 확인
2. 문법이 올바른지 확인 (보통 {#id})
3. ID에 유효하지 않은 문자가 포함되지 않았는지 확인
4. 다른 Markdown 프로세서 사용 시도

ID 충돌

동일한 문서에 여러 개의 동일한 ID가 있으면 예측할 수 없는 링킹 동작을 일으킬 수 있습니다:

## 문제 {#문제} <!-- 첫 번째 ID -->

...

## 일반적인 문제 {#문제} <!-- 중복 ID, 문제를 일으킬 수 있음 -->

ID 충돌을 피하는 해결책:

## 문제 {#문제-설명}

...

## 일반적인 문제 {#일반적인-문제}

공백과 특수 문자

일부 Markdown 프로세서는 ID의 공백과 특수 문자를 일관되지 않게 처리합니다:

<!-- 일부 플랫폼에서 문제가 있을 수 있음 -->
## 고급 설정 {#고급 설정}

<!-- 더 안전한 접근 방법 -->
## 고급 설정 {#고급-설정}

관련 문법

• 링크 - 기본 링크 문법
• 목차 - 자동 생성된 목차
• 각주 - 참조 및 설명 추가

도구 및 플러그인

자동 생성된 목차

많은 도구가 제목과 제목 ID를 기반으로 자동으로 목차를 생성할 수 있습니다:

[[toc]]

# 1장 {#1장}

## 1.1절 {#1-1절}

# 2장 {#2장}

제목 ID 검사 도구

• markdownlint: 제목 ID 일관성 검사 구성 가능
• remark-lint: 제목 ID 검사 및 자동 수정 제공
• markdown-toc: 링크가 있는 목차 자동 생성

---

제목 ID는 Markdown 문서의 사용성과 접근성을 향상시키는 중요한 도구입니다. 표준화된 제목 ID를 사용하여 탐색과 참조를 용이하게 하는 안정적인 링크 구조를 생성할 수 있으며, 문서를 더욱 전문적이고 사용자 친화적으로 만들 수 있습니다.