標題 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:
- 轉換為小寫字母
- 刪除或替換特殊字符
- 用連字符替換空格
- 刪除重復連字符
- 確保 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 不生效:
- 檢查平台是否支持自定義標題 ID
- 確認語法是否正確(通常是
{#id}
) - 驗證 ID 中是否包含無效字符
- 嘗試使用不同的 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,您可以創建穩定的鏈接結構,便於導航和引用,使您的文檔更加專業和易於使用。