扩展语法
除了 CommonMark 标准语法和 GFM 扩展外，许多 Markdown 处理器还支持额外的扩展语法。这些扩展让你的文档功能更加丰富。
本章介绍常用的扩展语法，包括定义列表、上标下标、高亮文本、Emoji 等。
定义列表
定义列表用于展示术语及其定义，常见于技术文档的术语表、API 参数说明等场景。
基本语法
术语独占一行，定义以冒号开头并缩进：
Markdown
: 一种轻量级标记语言，由 John Gruber 于 2004 年创建。
CommonMark
: Markdown 的标准化规范，解决了原始实现不一致的问题。
GFM
: GitHub Flavored Markdown，GitHub 在 CommonMark 基础上的扩展。
渲染效果：
Markdown : 一种轻量级标记语言，由 John Gruber 于 2004 年创建。
CommonMark : Markdown 的标准化规范，解决了原始实现不一致的问题。
GFM : GitHub Flavored Markdown，GitHub 在 CommonMark 基础上的扩展。
多个定义
同一个术语可以有多个定义：
Python
: 一种高级编程语言
: 一种爬行动物（蟒蛇）
渲染效果：
Python : 一种高级编程语言 : 一种爬行动物（蟒蛇）
多段落定义
定义可以包含多个段落，后续段落需要缩进：
API
: Application Programming Interface，应用程序接口。
API 定义了软件组件之间交互的规则和协议。通过 API，开发者可以在不了解内部实现的情况下使用其他软件的功能。
: 现代 API 通常以 REST 或 GraphQL 形式提供。
定义列表中的格式化
定义内容支持 Markdown 格式：
函数参数
: `name` - 用户名称，类型为 `string`
: `age` - 用户年龄，类型为 `number`
: `callback` - 回调函数，可选参数
示例：`function register(name, age, callback) {}`
兼容性说明
定义列表不是 CommonMark 标准的一部分，支持情况如下：
| 处理器/平台 | 支持情况 |
|---|---|
| PHP Markdown Extra | 支持（首创） |
| Python-Markdown | 支持（需扩展） |
| markdown-it | 支持（需插件） |
| Pandoc | 支持 |
| GitHub | 不支持 |
| GitLab | 不支持 |
如果目标平台不支持，可以使用 HTML 的 <dl> 标签：
<dl>
<dt>术语</dt>
<dd>定义内容</dd>
</dl>
上标与下标
上标和下标用于数学公式、化学式、脚注标记等场景。
上标
使用 ^ 符号包围（部分处理器支持）：
X^2^ 表示 X 的平方
2^10^ = 1024
渲染效果：X^2^ 表示 X 的平方
使用 HTML 标签（通用方法）：
X<sup>2</sup> 表示 X 的平方
第 3<sup>rd</sup> 代产品
渲染效果：X2 表示 X 的平方
下标
使用 ~ 符号包围（部分处理器支持）：
H~2~O 是水的化学式
CO~2~ 是二氧化碳
渲染效果：H2O 是水的化学式
使用 HTML 标签（通用方法）：
H<sub>2</sub>O 是水的化学式
a<sub>n</sub> 表示数列的第 n 项
渲染效果：H2O 是水的化学式
应用场景
化学方程式：
2H<sub>2</sub> + O<sub>2</sub> → 2H<sub>2</sub>O
渲染效果：2H2 + O2 → 2H2O
数学符号：
x<sub>1</sub>, x<sub>2</sub>, ..., x<sub>n</sub>
a<sup>2</sup> + b<sup>2</sup> = c<sup>2</sup>
脚注引用：
这是一个重要观点<sup>[1]</sup>。
兼容性说明
上标下标语法支持情况：
| 处理器/平台 | ^ ~ 语法 | HTML 标签 |
|---|---|---|
| Markdown-it | 支持（需插件） | 支持 |
| Pandoc | 支持 | 支持 |
| GitHub | 不支持 | 支持 |
| GitLab | 不支持 | 支持 |
推荐使用 HTML 标签以获得更好的兼容性。
高亮文本
高亮文本用于突出显示重要内容，类似于荧光笔标记效果。
基本语法
使用双等号 == 包围（部分处理器支持）：
这是一段 ==高亮文本==，用于强调重要内容。
渲染效果：这是一段 ==高亮文本==，用于强调重要内容。
使用 HTML 标签（通用方法）：
这是一段 <mark>高亮文本</mark>，用于强调重要内容。
渲染效果：这是一段 高亮文本，用于强调重要内容。
应用场景
搜索结果高亮：
搜索关键词 "markdown" 的结果：
...学习 <mark>Markdown</mark> 的最佳实践...
...<mark>Markdown</mark> 是一种轻量级标记语言...
代码审查注释：
问题在 <mark>第 42 行</mark>，变量未初始化。
重点强调：
注意事项：
- <mark>不要删除配置文件</mark>
- 定期备份数据
- <mark>生产环境谨慎操作</mark>
兼容性说明
| 处理器/平台 | == 语法 | HTML 标签 |
|---|---|---|
| Obsidian | 支持 | 支持 |
| Markdown-it | 支持（需插件） | 支持 |
| GitHub | 不支持 | 不支持 |
| GitLab | 不支持 | 不支持 |
| Typora | 支持 | 支持 |
注意：GitHub 渲染时会忽略 <mark> 标签。如需在 GitHub 上实现类似效果，可以使用粗体或代码格式替代。
Emoji 表情
Emoji 为文档增添视觉元素，使内容更生动。
直接复制粘贴
最简单的方法是直接复制 Emoji 并粘贴到 Markdown 文件中：
今天天气真好！☀️
项目状态：✅ 已完成
重要提醒：⚠️ 请注意安全
渲染效果：
今天天气真好！☀️
项目状态：✅ 已完成
重要提醒：⚠️ 请注意安全
使用 Emoji 短代码
部分 Markdown 处理器支持 Emoji 短代码，格式为 :emoji_name:：
Gone camping! :tent: Be back soon.
That is so funny! :joy:
I love Markdown! :heart:
渲染效果：
Gone camping! ⛺ Be back soon.
That is so funny! 😂
I love Markdown! ❤️
常用 Emoji 短代码
| 分类 | Emoji | 短代码 |
|---|---|---|
| 表情 | 😄 | :smile: |
| 表情 | 😂 | :joy: |
| 表情 | 😍 | :heart_eyes: |
| 手势 | 👍 | :thumbsup: |
| 手势 | 👏 | :clap: |
| 手势 | ✌️ | :victory_hand: |
| 符号 | ❤️ | :heart: |
| 符号 | ⭐ | :star: |
| 符号 | ✅ | :white_check_mark: |
| 符号 | ❌ | :x: |
| 符号 | ⚠️ | :warning: |
| 物体 | 📝 | :memo: |
| 物体 | 📚 | :books: |
| 物体 | 🚀 | :rocket: |
Emoji 使用建议
适合使用的场景：
- 项目 README 文件的状态标记
- 轻松的博客文章
- 团队内部文档
- Pull Request 描述
不适合使用的场景：
- 正式的技术文档
- 学术论文
- 商务合同
- API 文档
兼容性说明
| 处理器/平台 | Emoji 字符 | 短代码 |
|---|---|---|
| GitHub | 支持 | 支持 |
| GitLab | 支持 | 支持 |
| Obsidian | 支持 | 不支持 |
| Typora | 支持 | 不支持 |
| VS Code | 支持 | 需插件 |
标题 ID
为标题添加自定义 ID，便于创建锚点链接。
基本语法
在标题后使用花括号指定 ID：
### 安装指南 \{#installation}
### 配置说明 \{#configuration}
### 常见问题 \{#faq}
链接到标题 ID
创建指向标题的链接：
请参阅 [安装指南](#installation) 了解详情。
详细配置请看 [配置说明](#configuration)。
自动生成的标题 ID
大多数 Markdown 处理器会自动为标题生成 ID。生成规则通常是：
- 转换为小写
- 空格替换为连字符
- 移除特殊字符
## Getting Started
自动生成的 ID 是 `getting-started`，可以直接链接：
[快速开始](#getting-started)
跨文档链接
链接到其他文档的标题：
详见 [API 文档 - 认证部分](./api.md#authentication)
参考 [配置指南 - 环境变量](./config.md#environment-variables)
兼容性说明
| 处理器/平台 | 自定义 ID | 自动 ID |
|---|---|---|
| Markdown-it | 支持（需插件） | 支持 |
| Pandoc | 支持 | 支持 |
| GitHub | 不支持 | 支持 |
| GitLab | 不支持 | 支持 |
| Docusaurus | 支持 | 支持 |
缩写
为缩写词添加解释，鼠标悬停时显示完整含义。
基本语法
*[HTML]: HyperText Markup Language
*[CSS]: Cascading Style Sheets
*[API]: Application Programming Interface
HTML 和 CSS 是网页开发的基础技术。
使用 API 可以实现不同软件之间的通信。
渲染效果：鼠标悬停在 HTML、CSS、API 上会显示完整解释。
使用场景
*[GFM]: GitHub Flavored Markdown
*[CommonMark]: Markdown 的标准化规范
GFM 在 CommonMark 基础上增加了表格、任务列表等功能。
兼容性说明
缩写语法支持有限，主要在 PHP Markdown Extra 和 Python-Markdown 中支持。GitHub、GitLab 等平台不支持此语法。
YAML Frontmatter
在文件开头添加 YAML 元数据，用于静态网站生成器、博客系统等。
基本语法
使用 --- 包围 YAML 内容，放在文件最开头：
---
title: Markdown 扩展语法指南
date: 2024-01-15
author: 张三
tags:
- Markdown
- 教程
categories: 技术文档
---
# Markdown 扩展语法指南
正文内容...
常用字段
| 字段 | 说明 | 示例 |
|---|---|---|
title | 文档标题 | title: 我的第一篇文章 |
date | 发布日期 | date: 2024-01-15 |
author | 作者 | author: 张三 |
tags | 标签 | tags: [Markdown, 教程] |
categories | 分类 | categories: 技术 |
description | 描述 | description: 文档简介 |
draft | 是否草稿 | draft: true |
slug | URL 别名 | slug: markdown-guide |
不同系统的字段
Hexo 博客：
---
title: 文章标题
date: 2024-01-15 10:00:00
updated: 2024-01-20 15:30:00
categories:
- [技术, 前端]
tags:
- Markdown
- 教程
---
Docusaurus：
---
sidebar_position: 1
title: 教程标题
description: 教程描述
keywords:
- 关键词1
- 关键词2
---
Hugo：
---
title: "文章标题"
date: 2024-01-15
draft: false
weight: 10
---
Frontmatter 的作用
- 内容管理：标题、日期、作者等元信息
- 分类归档：标签、分类便于组织内容
- 模板渲染：控制页面布局和样式
- SEO 优化：设置描述、关键词
- 发布控制：草稿状态、发布时间
兼容性说明
Frontmatter 本身是纯文本，任何编辑器都能打开。但元数据的解析和处理依赖于具体的静态网站生成器或内容管理系统。
组合使用
扩展语法可以与标准语法组合使用，创建更丰富的文档：
---
title: API 参数说明
date: 2024-01-15
---
# API 参数说明
## 用户接口 \{#user-api}
### `register(name, age)`
注册新用户。
**参数：**
name
: 用户名称，类型为 `string`，长度 2-20 个字符
: 必须是有效的 UTF-8 字符
age
: 用户年龄，类型为 `number`，范围 1-150
**返回值：**
返回用户对象，包含 `id`、`name`、`age` 字段。
**示例：**
```javascript
const user = register('张三', 25);
// { id: 1, name: '张三', age: 25 }
[!WARNING] 年龄参数必须为正整数，否则会抛出异常。
状态： ✅ 已实现 | 🚧 测试中 | ⏳ 计划中
## 小结
本章学习了 Markdown 的扩展语法：
1. **定义列表**：术语与定义的对应关系
2. **上标下标**：数学公式、化学式
3. **高亮文本**：突出显示重要内容
4. **Emoji**：增添视觉元素
5. **标题 ID**：自定义锚点链接
6. **缩写**：缩写词解释
7. **Frontmatter**：YAML 元数据
使用扩展语法时，需要注意目标平台的兼容性。对于不支持的平台，可以使用 HTML 标签或替代方案。
## 练习
1. 创建一个术语表，使用定义列表展示技术术语
2. 编写一个化学方程式文档，使用上标下标
3. 为项目 README 添加 Emoji 状态标记
4. 创建一个包含 Frontmatter 的博客文章模板