定義列表

定義列表是 Markdown 的擴展功能，用於創建術語及其對應定義的列表，常用於詞匯表、術語解釋或參數說明等場景。

基本語法

基本格式

定義列表的基本格式由術語和定義組成，術語單獨一行，定義在下一行以冒號開始：

術語
: 定義內容

渲染效果：

術語 : 定義內容

多個術語和定義

Markdown
: 一種輕量級標記語言
: 由 John Gruber 創建於 2004 年

HTML
: 超文本標記語言
: 用於創建網頁的標准標記語言

渲染效果：

Markdown : 一種輕量級標記語言 : 由 John Gruber 創建於 2004 年

HTML : 超文本標記語言 : 用於創建網頁的標准標記語言

高級用法

多行定義

定義內容可以包含多行，後續行需要縮進：

術語
: 這是第一行定義內容
  這是第二行，需要縮進至少一個空格
  
  這是新段落，需要縮進至少一個空格並且前面有空行

渲染效果：

術語 : 這是第一行定義內容 這是第二行，需要縮進至少一個空格

這是新段落，需要縮進至少一個空格並且前面有空行

在定義中使用其他 Markdown 元素

定義內容中可以使用其他 Markdown 元素，如鏈接、強調、代碼等：

Markdown 語法
: **Markdown** 支持多種文本格式化：
  - *斜體* 和 **粗體**
  - [鏈接](https://www.markdownlang.com)
  - `行內代碼`
  - > 引用塊
  - 列表和其他元素

渲染效果：

Markdown 語法 : Markdown 支持多種文本格式化：

• 斜體 和 粗體
• 鏈接
• 行內代碼

• 引用塊

• 列表和其他元素

嵌套定義列表

在某些 Markdown 實現中，可以創建嵌套的定義列表：

外層術語
: 外層定義

  內層術語
  : 內層定義
  : 另一個內層定義

渲染效果（在支持的平台上）：

外層術語 : 外層定義

內層術語 : 內層定義 : 另一個內層定義

兼容性和實現差異

不同平台支持情況

平台/工具	定義列表支持	特殊語法	嵌套支持
GitHub Markdown	❌	-	-
GitLab Markdown	✅	標准	✅
Jekyll（kramdown）	✅	標准	✅
Hugo	✅	標准	✅
CommonMark	❌	-	-
VitePress	✅	標准	✅
Pandoc	✅	標准	✅

HTML 輸出格式

大多數 Markdown 處理器會將定義列表轉換為 HTML <dl>, <dt> 和 <dd> 元素：

<dl>
  <dt>術語</dt>
  <dd>定義內容</dd>
  
  <dt>另一個術語</dt>
  <dd>另一個定義</dd>
</dl>

不同語法變體

某些處理器可能需要不同的語法變體：

<!-- 標准語法 -->
術語
: 定義

<!-- 緊湊型語法（某些處理器） -->
術語：定義

<!-- 額外空格語法（某些處理器） -->
術語
  : 定義

使用場景

術語表

定義列表非常適合創建術語表或詞匯表：

## 編程術語表

API
: 應用程序編程接口，一組允許不同軟件應用程序相互通信的規則。

框架
: 為應用程序開發提供標准化結構的軟件庫。

Git
: 一種分布式版本控制系統，用於跟蹤項目開發過程中的變化。

IDE
: 集成開發環境，包含代碼編輯器和各種開發工具的軟件應用程序。

渲染效果：

編程術語表

API : 應用程序編程接口，一組允許不同軟件應用程序相互通信的規則。

框架 : 為應用程序開發提供標准化結構的軟件庫。

Git : 一種分布式版本控制系統，用於跟蹤項目開發過程中的變化。

IDE : 集成開發環境，包含代碼編輯器和各種開發工具的軟件應用程序。

API 文檔

定義列表在 API 文檔中用於解釋參數或選項：

## 請求參數

user_id
: **必填** - 用戶的唯一標識符。
: 類型: `integer`

name
: **可選** - 用戶的顯示名稱。
: 類型: `string`
: 默認值: `null`

status
: **可選** - 用戶狀態。
: 類型: `string`
: 允許的值: `active`, `inactive`, `suspended`
: 默認值: `active`

渲染效果：

請求參數

user_id : 必填 - 用戶的唯一標識符。 : 類型: integer

name : 可選 - 用戶的顯示名稱。 : 類型: string : 默認值: null

status : 可選 - 用戶狀態。 : 類型: string : 允許的值: active, inactive, suspended : 默認值: active

配置說明

定義列表也適合用於解釋配置選項：

## 配置選項

debug
: 啟用或禁用調試模式。
: 類型: `boolean`
: 默認值: `false`
: 示例: `debug: true`

log_level
: 日志記錄的詳細程度。
: 類型: `string`
: 允許的值: `error`, `warn`, `info`, `debug`
: 默認值: `info`
: 示例: `log_level: debug`

max_connections
: 允許的最大同時連接數。
: 類型: `integer`
: 默認值: `100`
: 示例: `max_connections: 500`

最佳實踐

格式一致性

✅ 推薦做法：

1. **保持術語與定義的一致風格**：
   - 術語使用簡潔的名詞或短語
   - 定義以句子格式，首字母大寫，句末加句號
   - 對於多行定義，保持一致的縮進

2. **合理分組**：
   - 相關術語放在一起
   - 使用標題分隔不同類別的定義列表

3. **對於技術術語**：
   - 包括類型信息
   - 添加示例
   - 標明必填或可選

❌ 避免做法：

1. 術語過長，超過一行
2. 術語中使用大段格式化文本
3. 缺少明確的分類
4. 定義中包含不相關信息

替代方案

在不支持定義列表的平台上，可以使用其他格式模擬：

<!-- 使用粗體和縮進 -->
**術語**
  定義內容

**另一個術語**
  另一個定義內容

<!-- 使用表格 -->
| 術語 | 定義 |
|------|------|
| API | 應用程序編程接口 |
| IDE | 集成開發環境 |

<!-- 使用標題和段落 -->
### 術語
定義內容

### 另一個術語
另一個定義內容

實際應用示例

軟件文檔

## 系統要求

操作系統
: **Windows**: Windows 10 或更高版本
: **macOS**: macOS 10.14 (Mojave) 或更高版本
: **Linux**: Ubuntu 18.04+、Debian 10+、CentOS 7+

硬件
: **處理器**: 四核 2.0 GHz 或更快
: **內存**: 最少 8GB RAM，推薦 16GB
: **存儲**: 至少 10GB 可用空間，SSD 存儲

網絡
: 寬帶互聯網連接 (最少 10 Mbps)
: 允許以下端口的出站連接：80、443、22

學術文檔

## 研究術語

數據集
: 用於分析或評估的數據集合。
: 本研究使用了從公共存儲庫獲取的樣本 (n=1000)。

變量
: **自變量**: 研究者操控的輸入因素。
  在本研究中，自變量是環境溫度。
  
: **因變量**: 研究中被測量的輸出因素。
  在本研究中，因變量是處理速度。
  
: **控制變量**: 在實驗中保持不變的因素。
  在本研究中包括濕度和處理器負載。

顯著性水平
: 統計分析中用於決定結果是否有意義的概率閾值。
: 本研究采用 p < 0.05 作為顯著性標准。

常見問題解決

定義列表不顯示

如果您的定義列表沒有正確顯示：

1. 檢查平台是否支持定義列表語法
2. 確保術語和定義之間沒有空行
3. 驗證冒號前面是否有合適的空格（某些處理器可能有具體要求）
4. 嘗試增加縮進或更改語法變體

嵌套列表問題

嵌套定義列表可能在某些處理器中有問題：

1. 增加縮進層級（例如，內層術語使用4或8個空格）
2. 確保每層之間有適當的空行
3. 如果持續出現問題，考慮使用其他結構（如常規列表）

格式問題

如果定義中的格式不正確：

1. 檢查是否為所有段落和元素保持了正確的縮進
2. 確保塊級元素（如代碼塊、列表）在定義中有正確的空行分隔
3. 嘗試增加縮進量

相關語法

• 列表 - 基礎列表語法
• 表格 - 結構化數據展示
• 圍欄代碼塊 - 代碼塊語法

工具和插件

• markdown-it-deflist: 為 markdown-it 添加定義列表支持
• kramdown: 原生支持定義列表的 Markdown 解析器
• remark-definition-list: remark 解析器的定義列表插件

---

定義列表是一種強大的 Markdown 擴展功能，特別適合創建術語、參數和配置的解釋文檔。盡管不是所有 Markdown 處理器都支持此語法，但在支持的平台上，它為技術文檔提供了清晰、結構化的格式，使復雜信息更易於理解和參考。