Skip to content

標題 ID

標題 ID 是 Markdown 的擴展功能,允許為標題添加自定義標識符,便於創建精確鏈接和控制文檔結構。

基本語法

添加標題 ID

標題 ID 使用大括號語法,放在標題文本後面:

markdown
## 我的標題 {#custom-id}

渲染效果

HTML 輸出會將這個自定義 ID 添加到標題元素上:

html
<h2 id="custom-id">我的標題</h2>

多級標題 ID

各級標題都可以添加自定義 ID:

markdown
# 一級標題 {#first-level}

## 二級標題 {#second-level}

### 三級標題 {#third-level}

#### 四級標題 {#fourth-level}

應用場景

創建錨點鏈接

有了自定義 ID,您可以創建指向文檔內特定部分的鏈接:

markdown
[點擊跳轉到我的標題](#custom-id)

...其他內容...

## 我的標題 {#custom-id}

渲染效果

點擊鏈接將會直接跳轉到帶有 custom-id 的標題處。

外部鏈接到文檔特定部分

自定義 ID 也便於從外部文檔鏈接到特定內容:

markdown
[鏈接到其他文檔的特定章節](other-doc.html#specific-section)

URL 分享特定章節

帶有 ID 的標題可以通過 URL 分享給他人,指向文檔的特定章節:

https://www.markdownlang.com/documentation.html#installation-guide

高級用法

多詞標題 ID

當標題包含多個詞時,標題 ID 通常使用連字符連接:

markdown
## 安裝和配置指南 {#installation-and-configuration}

目錄生成和標題 ID

許多 Markdown 處理器會自動根據標題內容生成 ID。通過自定義 ID,您可以確保目錄鏈接不受標題內容變化的影響:

markdown
## 入門指南 {#getting-started}

即使稍後將標題改為"開始使用",鏈接仍然有效,因為 ID 保持不變。

國際化和非英文字符

對於非英文標題,自定義 ID 特別有用,因為它提供了穩定的英文標識符:

markdown
## 安裝說明 {#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
## Getting Started#getting-started
## FAQ & Help#faq-help
## 快速入門#快速入門#section-1(因平台而異)

最佳實踐

標題 ID 命名規范

markdown
✅ 推薦做法:

1. **使用簡潔描述性ID**
   - `{#installation}`
   - `{#api-reference}`
   - `{#troubleshooting}`

2. **保持一致的命名風格**
   - 全部小寫
   - 使用連字符分隔詞語
   - 避免使用下劃線或駝峰命名

3. **保持ID穩定性**
   - 避免頻繁更改ID
   - 在修改標題文本時保留原ID

❌ 避免做法:

1. 使用特殊字符(如 `!@#$%^&*()`
2. 使用非描述性ID(如 `{#section1}`
3. 創建過長的ID
4. 使用空格或標點符號

文檔結構與標題 ID

對於大型文檔,建議為主要章節使用規范化的 ID,便於導航:

markdown
# 產品文檔 {#product-docs}

## 介紹 {#introduction}

## 安裝 {#installation}

### Windows 安裝 {#installation-windows}

### macOS 安裝 {#installation-macos}

### Linux 安裝 {#installation-linux}

## 配置 {#configuration}

## API 參考 {#api-reference}

## 常見問題 {#faq}

實際應用示例

技術文檔中的標題 ID

技術文檔中的標題 ID 可以幫助用戶直接鏈接到特定章節:

markdown
# API 文檔 {#api-documentation}

## 認證 {#authentication}

### 獲取 API 密鑰 {#get-api-key}

### OAuth 認證 {#oauth}

## 端點 {#endpoints}

### 用戶端點 {#endpoints-users}

### 產品端點 {#endpoints-products}

學術論文中的標題 ID

學術論文可以使用標題 ID 創建引用和交叉引用:

markdown
# 研究方法 {#methodology}

如[研究結果](#results)所示,我們的方法在多個測試案例中表現良好。

...

# 研究結果 {#results}

本節展示我們在[研究方法](#methodology)中描述的實驗結果。

常見問題解決

標題 ID 不生效

如果您的標題 ID 不生效:

  1. 檢查平台是否支持自定義標題 ID
  2. 確認語法是否正確(通常是 {#id}
  3. 驗證 ID 中是否包含無效字符
  4. 嘗試使用不同的 Markdown 處理器

ID 沖突

如果同一文檔中有多個相同的 ID,可能會導致鏈接行為不可預測:

markdown
## 問題 {#issue} <!-- 第一個ID -->

...

## 常見問題 {#issue} <!-- 重復的ID,可能導致問題 -->

避免 ID 沖突的解決方案:

markdown
## 問題 {#issue-description}

...

## 常見問題 {#common-issues}

空格和特殊字符

有些 Markdown 處理器對 ID 中的空格和特殊字符處理不一致:

markdown
<!-- 可能在某些平台上有問題 -->
## 高級設置 {#advanced settings}

<!-- 更安全的方式 -->
## 高級設置 {#advanced-settings}

相關語法

工具和插件

自動生成目錄

許多工具可以根據標題和標題 ID 自動生成目錄:

markdown
[[toc]]

# 第一章 {#chapter-1}

## 1.1 節 {#section-1-1}

# 第二章 {#chapter-2}

標題 ID 檢查工具

  • markdownlint: 可配置為檢查標題 ID 的一致性
  • remark-lint: 提供標題 ID 的檢查和自動修復
  • markdown-toc: 自動生成帶有鏈接的目錄

標題 ID 是提高 Markdown 文檔可用性和可訪問性的重要工具。通過使用標准化的標題 ID,您可以創建穩定的鏈接結構,便於導航和引用,使您的文檔更加專業和易於使用。

由 Markdownlang.com 整理創建