定义列表

定义列表是 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 处理器都支持此语法，但在支持的平台上，它为技术文档提供了清晰、结构化的格式，使复杂信息更易于理解和参考。