第五章 Markdown 扩展语法

团队准备维护一份网站开发计划：既要看清哪些任务做完了，也要比较技术选型、追踪用户请求经过的环节。上一章学的标题、列表和代码能写好正文，但表达这些信息还得多几种写法。我们把任务列表、表格和 Mermaid 加进 website_plan.md，再用删除线记录方案变更；数学公式和 HTML 则分别放到科学笔记和折叠说明里试试。

这些扩展在不同工具里都很常见：

• 表格；
• 任务列表；
• 删除线；
• 数学公式；
• Mermaid 图表；
• HTML。

有一点先记住：这些写法不全属于 Markdown 核心语法。有些来自：

• GFM；
• CommonMark 之外的扩展；
• Markdown 编辑器自己的增强；
• 网站生成器自己的插件；
• JavaScript 渲染库；
• 数学或图表工具。

所以学写法时也要留意：一个工具支持，不代表别的工具也支持。

5.1 扩展边界

Markdown 最初追求简单、易读、易写，核心语法也就保持得很精简：

# 标题

- 列表

[链接](https://example.com)

> 引用

这些写法已经能应付多数普通文章。后来 Markdown 被用到更多场景里，人们又希望它能处理：

表格
任务管理
数学公式
流程图
复杂布局

于是各个平台陆续加上自己的扩展。大致可以这么看：

Markdown 核心语法
        ↓
     扩展能力
        ↓
┌───────┼────────┐
↓       ↓        ↓
GFM   LaTeX   Mermaid

5.2 表格

信息需要按行列并排比较时，表格很方便：

| 姓名 | 年龄 | 城市 |
| --- | --- | --- |
| 小明 | 18 | 长沙 |
| 小红 | 20 | 北京 |

第一行是表头，中间用分隔行，后面才是数据：

表头
↓
分隔行
↓
数据

换成实际内容就是这样：

| 语言 | 类型 |
| --- | --- |
| Python | 编程语言 |
| HTML | 标记语言 |

列分隔

竖线 | 用来分隔表格中的列：

|

例如：

| Python | 简单易学 |

这行有两列：左边是技术，右边是用途。写多行时，每行都用竖线隔开：

| 技术 | 用途 |
| --- | --- |
| Python | 后端开发 |
| Vue | 前端开发 |
| MySQL | 数据库 |

分隔行

表头下面要加一行短横线，告诉渲染器列名到这里结束：

| --- | --- |

例如：

| 姓名 | 分数 |
| --- | --- |
| 小明 | 90 |
| 小红 | 95 |

它不是一行数据，而是表头和内容之间的分界。

对齐

不少 Markdown 工具还支持用冒号设置对齐。冒号放在短横线左边表示左对齐：

| 姓名 | 分数 |
| :--- | :--- |
| 小明 | 90 |

两边都放冒号表示居中：

| 姓名 | 分数 |
| :---: | :---: |
| 小明 | 90 |

只在右边放冒号表示右对齐：

| 姓名 | 分数 |
| ---: | ---: |
| 小明 | 90 |

例如：

| 商品 | 数量 | 价格 |
| :--- | :---: | ---: |
| 键盘 | 2 | 299 |
| 鼠标 | 1 | 99 |

这张表里，商品左对齐，数量居中，价格右对齐。

表格用途

表格常用来整理：

• 参数说明；
• 功能对比；
• 配置项；
• 简单数据；
• 软件版本；
• 工具支持情况。

例如：

| 工具 | Markdown | Git | 插件 |
| --- | --- | --- | --- |
| VS Code | 支持 | 支持 | 丰富 |
| Typora | 支持 | 一般 | 较少 |
| Obsidian | 支持 | 可配合 | 丰富 |

这类信息放在表格里，比逐项看列表更容易横向比较。

选型表

继续编辑 website_plan.md，加上技术选型：

# 网站开发计划

## 技术选型

| 模块 | 技术 |
| --- | --- |
| 后端 | FastAPI |
| 前端 | Vue |
| 数据库 | PostgreSQL |

保存后打开预览，应该看到两列技术、三行数据。分隔行只用来标出表头，不会作为数据出现。如果仍看到竖线和短横线，检查预览工具是否支持表格。

排版限制

Markdown 表格胜在简单，复杂排版就不太合适，例如：

• 合并单元格或多层表头；
• 大量图片混排；
• 需要精确控制宽度、高度和整体布局。

如果表格已经复杂到：

需要合并很多单元格
+
需要精确布局
+
需要复杂样式

Markdown 表格可能就不是合适的工具，可以考虑：

• HTML；
• Excel；
• Word；
• 专业表格组件。

5.3 任务列表

任务列表可以标记完成状态，GitHub、Obsidian 等工具都常见。未完成的任务写成：

- [ ] 学习 Markdown

完成后把空框改成 x：

- [x] 学习标题

一份清单里可以混合两种状态：

- [x] 学习标题
- [x] 学习列表
- [ ] 学习表格
- [ ] 学习 Mermaid

预览时就能一眼看出哪些做完了，哪些还没做。

任务场景

比如学习计划：

## 本周学习计划

- [x] 安装 Python
- [x] 创建虚拟环境
- [ ] 学习 Flask
- [ ] 学习 FastAPI

项目发布前的检查也一样：

## 发布前检查

- [x] 完成首页
- [x] 完成登录
- [ ] 完成支付
- [ ] 部署服务器

写课程时也可以这么记进度：

## Markdown 课程

- [x] 第一章
- [x] 第二章
- [ ] 第三章

这样 Markdown 除了写文章，也能做简单的任务跟踪。

开发清单

在 website_plan.md 里加一份开发清单：

## 开发任务

- [x] 创建项目
- [x] 完成首页
- [ ] 完成登录
- [ ] 完成支付

预览里应该有两项已完成、两项未完成。能不能直接点击复选框要看工具；即使只能静态显示，状态也已经表达清楚了。

交互差异

- [ ] 任务

语法能表示任务状态，但交互效果要看具体工具：有的可以点击复选框，有的只会静态显示。

5.4 删除线

两边各加两个波浪号，就能给文字加删除线：

~~旧内容~~

例如：

课程价格：~~299 元~~ 199 元

或者：

- ~~安装旧版本~~
- 使用最新稳定版本

可以用它标出：

• 已废弃的内容或旧信息；
• 修改前的值；
• 已取消的事项。

变更记录

网站原计划用 Flask，后来改成 FastAPI，可以在开发计划里留下这条记录：

原计划使用 ~~Flask~~，后来调整为 FastAPI。

预览里 Flask 会带删除线，FastAPI 保持正常显示，变更前后的选型就都留住了。

兼容性

删除线现在很常见，但它不是最早的 Markdown 核心语法。GitHub、Typora、Obsidian 等工具通常支持，极简渲染器则未必。

5.5 数学公式

如果另写科学笔记，想表达分数、求和或矩阵，普通 Markdown 就不太够用。简单的公式可以直接写：

E = mc²

遇到下面这些形式，直接用文本就显得笨拙了：

分数
积分
矩阵
上下标
极限
求和

所以一些 Markdown 工具会额外支持 LaTeX 数学语法。LaTeX 不是 Markdown 的某个版本，而是常和 Markdown 搭配使用的公式写法：

Markdown
+
LaTeX 数学语法

这就是常见的组合方式。

行内公式

支持公式的工具通常用下面的写法表示行内公式：

$E = mc^2$

例如：

根据质能方程 $E = mc^2$ 可以得到……

公式会嵌在段落里。

块级公式

公式比较长，或者需要单独突出时，可以放在独立的一行：

$$
E = mc^2
$$

例如：

爱因斯坦质能方程：

$$
E = mc^2
$$

有些工具也支持 LaTeX 分数写法：

\frac{a}{b}

在块级公式中，\frac{a}{b} 会排成分数。

复杂公式

求和可以写成：

$$
\sum_{i=1}^{n} i
$$

积分写作：

$$
\int_a^b f(x)\,dx
$$

矩阵则是：

$$
\begin{bmatrix}
1 & 2 \\
3 & 4
\end{bmatrix}
$$

这些公式不是 Markdown 自己渲染的，通常由下面的工具负责：

MathJax
KaTeX
LaTeX 数学渲染器

公式预览

写下同一个公式：

$$
E = mc^2
$$

有些工具会把它渲染成公式，有些只会显示原文：

$$
E = mc^2
$$

文档要发布到多个平台时，先确认目标平台是否支持公式，尤其留意：

• GitHub、VitePress；
• Typora、Obsidian；
• 博客平台。

支持方式不一定相同。跟练时把 $$ 包围的质能方程存进科学笔记并预览：支持数学渲染的工具会显示独立公式；如果只看到 $ 和原文，就检查渲染设置。

5.6 Mermaid

另一个常用扩展是 Mermaid：用文本描述图表，例如：

```mermaid
flowchart LR
    A[开始] --> B[学习 Markdown]
    B --> C[编写文档]
```

当前工具支持 Mermaid 的话，这段代码就会变成流程图。

文本图表

用绘图软件做图，通常要拖拽图形、调整位置，再导出图片：

打开绘图软件
↓
拖拽图形
↓
调整位置
↓
导出 PNG
↓
插入文档

Mermaid 则直接写文本：

编写文本
↓
生成图表

例如：

图表源代码也是纯文本，可以跟 Markdown 一起保存、交给 Git 比较，也方便让 AI 帮忙修改。

图表类型

Mermaid 不只画流程图，也支持时序图、类图和状态图：

流程图

```mermaid
flowchart TD
    A[用户] --> B[前端]
    B --> C[FastAPI]
    C --> D[数据库]
```

时序图

```mermaid
sequenceDiagram
    User->>Web: 请求页面
    Web->>API: 请求数据
    API-->>Web: 返回数据
    Web-->>User: 显示页面
```

类图

```mermaid
classDiagram
    User --> Order
```

状态图

```mermaid
stateDiagram-v2
    [*] --> 待支付
    待支付 --> 已支付
    已支付 --> 已完成
```

请求流程

把流程图加到 website_plan.md 的“系统流程”小节，把节点改成“用户 → 网站 → FastAPI → PostgreSQL”。支持 Mermaid 的预览会显示四个相连的节点；如果看到的还是 flowchart 源码，检查工具是否支持 Mermaid。

图表渲染

即使写了：

```mermaid
...
```

从 Markdown 的角度看，这仍是代码块；Mermaid 渲染器再把它变成图表：

Markdown
↓
发现 mermaid 代码块
↓
Mermaid
↓
生成图表

目标软件没有集成 Mermaid 时，页面就只会显示源码。

图表选择

Mermaid 适合结构图和流程图：它是纯文本，方便 Git 比较、AI 修改，也不用另存图片。

需要自由排版或精细设计时，传统图片更合适，兼容性也通常更稳定，不依赖 Mermaid 渲染器。

简单选的话：

结构图 / 流程图
↓
优先考虑 Mermaid

复杂视觉设计
↓
优先考虑图片或专业绘图工具

5.7 HTML

不少 Markdown 实现允许在文档里直接写 HTML。例如 <br> 可以换行：

<br>

也可以用 <details> 折叠较长的说明：

<details>
  <summary>点击展开</summary>

  这里是详细内容。

</details>

支持 HTML 的环境会显示可展开区域。我们可以把部署注意事项放进去试试：点击标题应能展开内容；若只看到标签，检查工具是否允许原始 HTML。

补充写法

Markdown 不方便表达某些细节时，可以补一点 HTML。比如用 <kbd> 标出快捷键：

<kbd>Ctrl</kbd> + <kbd>C</kbd>

也可以用 <mark>：

<mark>重点内容</mark>

高亮一小段文字，或用 <div> 包住自定义内容：

<div>
  自定义内容
</div>

Markdown 优先

能写 HTML 不代表整篇文档都该用 HTML。比如没必要把普通内容写成：

<h1>标题</h1>
<p>正文</p>
<ul>
  <li>Python</li>
  <li>Java</li>
</ul>

Markdown 本来就能清楚表达：

# 标题

正文。

- Python
- Java

就不用换成 HTML。优先用 Markdown，遇到确实不方便表达的部分再补 HTML，文档会更好读，也更容易维护和迁移。

安全限制

原始 HTML 能不能用、哪些标签会被保留，都由平台决定。比如 <details> 可能可以正常显示，但 <script> 往往会被过滤：

<script>
  // 任意代码
</script>

如果文档里的脚本都能直接执行，就会有安全风险。因此很多平台只允许部分 HTML，或者干脆禁用原始 HTML。写之前先看目标工具的限制，别默认所有标签都会照常工作。

5.8 兼容性

表格、任务列表、LaTeX 和 Mermaid 常被统称为“Markdown 扩展”，但它们并不来自同一个标准：

表格
↓
常见于 GFM 等扩展

任务列表
↓
常见于 GFM

删除线
↓
常见于 GFM

LaTeX
↓
数学渲染能力

Mermaid
↓
独立图表工具

HTML
↓
Markdown 实现中的原始 HTML 支持

所以“扩展语法”只是个统称，具体还要看它来自哪种标准或工具。

平台差异

比如同一份文档里写了：

# 学习计划

- [x] Markdown
- [ ] FastAPI

~~旧计划~~

$$
E = mc^2
$$

```mermaid
flowchart LR
A --> B
```

功能丰富的编辑器可能都能显示；换成简单的渲染器，情况就可能是：

任务列表 → 支持
删除线 → 支持
数学公式 → 不支持
Mermaid → 不支持

显示效果取决于几件事：

Markdown 源码
+
Markdown 解析器
+
启用的扩展
+
渲染环境

迁移原则

文档要长期保存或在多个工具间迁移时，核心内容尽量用基础 Markdown，增强效果再用扩展。比如正文结构：

# Python

## 列表

## 字典

尽量保持这种基础写法。Mermaid、LaTeX 和 HTML 则属于额外能力：

Mermaid
LaTeX
HTML

即使目标工具不支持这些扩展，核心文字和结构仍然能读。

5.9 网站开发计划

来看看前面那份网站开发计划最后可以写成什么样：

# 网站开发计划

## 开发任务

- [x] 创建项目
- [x] 完成首页
- [ ] 完成登录
- [ ] 完成支付

## 技术选型

| 模块 | 技术 |
| --- | --- |
| 后端 | FastAPI |
| 前端 | Vue |
| 数据库 | PostgreSQL |

## 系统流程

```mermaid
flowchart LR
    A[用户] --> B[网站]
    B --> C[FastAPI]
    C --> D[PostgreSQL]
```

## 说明

原计划使用 ~~Flask~~，后来调整为 FastAPI。

<details>
  <summary>部署注意事项</summary>

  部署前确认数据库连接和环境变量。

</details>

这里把任务列表、表格、Mermaid、删除线和 HTML 放在了一起，已经超出 Markdown 核心语法。保存为 website_plan.md 后打开预览：确认任务状态、三行技术选型、四个流程节点、Flask 的删除线，以及可以展开的部署说明。数学公式留在前面的科学笔记里，不用为了凑语法塞进计划；某项没显示，再检查工具是否支持它。

5.10 选用原则

不用一上来就把所有扩展都学完，可以按需求和使用频率来选。日常最常遇到的是：

表格
任务列表
删除线

需要数学公式时再学 LaTeX；想画流程图或架构图，再看 Mermaid。

最后再考虑 HTML：

HTML

只有 Markdown 表达起来确实不方便时，再用它。

必要性

普通文章写一条提醒，直接写：

## 注意事项

请先备份数据。

没必要为了样式换成一大段 HTML：

<div class="custom-warning-box">
  请先备份数据。
</div>

同样，像“用户 → 网站 → 数据库”这样简单的关系：

用户 → 网站 → 数据库

也不必非用 Mermaid。扩展语法是为了解决表达问题，不是为了增加复杂度；核心 Markdown 说清楚了，就保持简单。

平台能力

工具各自支持的扩展不一样。比如编辑器可能支持：

表格
任务列表
数学公式
Mermaid

文档网站生成器可能还支持：

表格
代码高亮
自定义组件
Mermaid 插件

Git 托管平台常见的是：

GFM
任务列表
表格
代码块

知识管理软件还可能加入：

双向链接
块引用
嵌入
属性

后面选工具、比较语法差异时，还会再遇到这些功能。

5.11 小结

表格、任务列表、删除线、数学公式、Mermaid 和 HTML 都能补上核心语法不擅长表达的内容。不过它们来自不同扩展，工具支持也不一致。碰到一种新写法，可以先问：

1. 这是 Markdown 核心语法吗？
2. 如果不是，它属于哪一种扩展？
3. 我的目标平台是否支持？

下一章接着看 CommonMark、GFM 和各类软件扩展的区别，也会解释为什么同一份 .md 文件换个平台，显示效果就可能不一样。