文件格式
什么是 Markdown？语法、CommonMark 与 GFM
Markdown 是一种轻量级标记语言，只需几个符号就能为纯文本加上标题、列表和链接。本文介绍它的历史、标准，以及把 MD 文件转为 Word 或 PDF 时哪些内容能够保留。
作者: Hemen Dönüştür Editör Ekibi发布日期: 阅读约 8 分钟
想想软件项目里的 README、笔记应用中带标题的列表，或者在聊天应用里用星号加粗的文字。它们背后是同一个想法：Markdown。Markdown 是一种轻量级标记语言，只要在纯文本中加入几个简单的符号，就能定义标题、列表、链接和表格。文件在任何文本编辑器中都清晰可读，需要时又能转换成整洁的 HTML 页面、Word 文档或 PDF。本文将介绍 Markdown 的由来、核心语法、CommonMark 与 GitHub Flavored Markdown 的区别，以及转换 MD 文件时需要注意的地方。
什么是 Markdown？
Markdown 既是一套书写约定，也是把按这些约定写成的文本转换为 HTML 的工具的统称。文件通常以 .md 或 .markdown 扩展名保存。据其创造者 John Gruber 所说，最重要的设计目标是可读性：Markdown 文档应当能够以纯文本的形式原样发布，看起来不像是被标签或格式指令标记过。HTML 需要写 <strong>重要</strong> 的地方，Markdown 只需写 **重要**，即使是原始文本读起来也很自然。
简要历史
John Gruber 于 2004 年创造了 Markdown，Aaron Swartz 作为他的想法讨论伙伴参与其中。语法借鉴了纯文本电子邮件的习惯（用星号表示强调，用连字符表示列表），以及 setext 和 Textile 等更早的标记语言。Gruber 在其 Daring Fireball 网站上发布的 Perl 脚本 Markdown.pl，1.0.1 版的日期是 2004 年 12 月 17 日。
不过，Gruber 的说明是通过示例来解释的，而不是一份正式的规范。模棱两可的情形（嵌套列表、缩进代码块、混入 HTML）让每个实现都做出了自己的选择，同样的文本在不同工具中开始产生不同的输出。随后出现了两个重要的应对方案：
- CommonMark（2014 年）：由 John MacFarlane 牵头的规范，对 Markdown 做出无歧义的定义，并通过数百个示例使其可测试。最早的版本发布于 2014 年秋季；当前版本是 2024 年 1 月 28 日发布的 0.31.2。该规范尚未宣布进入 1.0。
- GitHub Flavored Markdown（GFM，2017 年）：GitHub 在 CommonMark 基础上制定的正式规范。它加入了表格、任务列表、删除线、扩展自动链接等扩展，并出于安全考虑过滤部分原始 HTML 标签。最新发布的规范是 2019 年 4 月 6 日的 0.29-gfm。
Markdown 也在互联网基础设施中获得了认可：2016 年 3 月发布的 RFC 7763 注册了 text/markdown 媒体类型（MIME 类型），并带有一个可选的 variant 参数，用来表明作者所使用的 Markdown 变体。
主要的 Markdown 变体
除了 CommonMark 和 GFM，还有其他一些广泛使用的变体。与 RFC 7763 同时发布的 RFC 7764 登记了其中几种，并给出了使用建议：
- Markdown Extra：早期的扩展，加入了脚注、定义列表和表格。
- MultiMarkdown：面向学术写作的变体，支持元数据、引文和交叉引用。
- Pandoc Markdown：Pandoc 转换器使用的变体，带有许多用于写书和论文的扩展。
一条实用的规则：如果文档只用到标题、列表、链接、代码和简单表格，它在几乎所有地方看起来都一样。如果依赖脚注、定义列表或特殊块类型，请先确认目标环境支持哪种变体。
核心语法
日常需要的 Markdown 语法几分钟就能学会：
# 一级标题
## 二级标题
这个段落包含**粗体**、*斜体*和 `代码`。
- 无序列表
- 第二项
- 缩进的子项
1. 有序列表
2. 第二步
[链接文字](https://example.com)
> 引用块
```
多行代码块
```GFM 加入的表格和任务列表写法如下：
| 格式 | 扩展名 |
|------|--------|
| Markdown | .md |
| 纯文本 | .txt |
- [x] 写初稿
- [ ] 审阅段落之间用空行分隔。在大多数实现中，单个换行被视为同一段落的一部分；要强制换行，请在行尾加两个空格。你也可以直接在 Markdown 中写 HTML。CommonMark 允许这样做，不过 GFM 等环境出于安全考虑会屏蔽某些标签。
Markdown 用在哪里？
- 软件开发：README、更新日志和贡献指南，以及 GitHub、GitLab 等平台上的议题和代码审查评论。
- 技术文档：用 Markdown 文件构建网站的静态网站生成器。
- 笔记：许多笔记应用以 Markdown 存储或导出笔记。
- 聊天和社区平台：Reddit、Discord 等平台使用 Markdown 的变体。
- 写作与出版：借助 Pandoc 等工具，从同一份 Markdown 源文件生成 HTML、PDF、DOCX 和 EPUB。
- AI 工具：基于对话的 AI 助手经常用 Markdown 来排版回答。
优点与缺点
| 优点 | 缺点 |
|---|---|
| 原始形式也清晰可读 | 不同变体的行为不同 |
| 纯文本：体积小、可移植、便于版本控制 | 没有字体、颜色和页面版式 |
| 可以轻松转换为 HTML、PDF 和 Word | 不支持复杂表格（合并单元格） |
| 几分钟就能学会 | 图片位于单独的文件中 |
| 不绑定任何程序 | 空格和缩进的错误会改变输出 |
哪些程序可以打开 Markdown？
由于 Markdown 是纯文本，任何文本编辑器都能打开，包括记事本和“文本编辑”。如果想看到排版后的预览，可以使用 Visual Studio Code 内置的 Markdown 预览，或 Obsidian、Typora 等专用编辑器。GitHub 和 GitLab 会自动渲染仓库中的 .md 文件。而 Word 不会把 Markdown 作为带格式的文本打开，因此需要先转换文件。
常见问题及解决方法
列表或标题没有正确显示
CommonMark 要求标题符号后面有一个空格：要写 ## 标题，而不是 ##标题。紧跟在段落后面的列表，通常也需要在两者之间留一个空行才能正确显示。
几行文字连在了一起
单个换行不会分出新段落。要开始新段落，请留一个空行；要在段落内换行，请在行尾加两个空格。
表格在一个平台上正常，在另一个平台上不正常
表格既不属于 Gruber 最初的 Markdown，也不属于 CommonMark 的核心，而是来自 GFM 等扩展。请确认目标平台支持哪种变体。
以数字开头的段落变成了有序列表
像“2024. 是忙碌的一年”这样的行以数字和句点开头，可能会被解析为列表。用反斜杠转义句点（2024\.）即可避免。
Markdown 文件转换技巧
在我们的转换器上，Markdown 文件会上传到我们的服务器，并在 30 分钟内删除。读取时，我们使用 Markdig 库，并启用 CommonMark 和 GitHub 风格的扩展（表格、任务列表、脚注、自动链接）。
- Markdown 转 PDF 和 Markdown 转 Word 会保留标题、列表、代码块、引用块和带边框的表格。任务列表的复选框会转换为 ☑ 和 ☐ 字符，以便在 Word 和 PDF 中依然可见。正文默认使用 12 磅衬线字体，代码块使用等宽字体。
- Markdown 转 HTML 可以把 README 变成一个声明了字符编码的独立网页。
- 反方向上，Word 转 Markdown、HTML 转 Markdown 和 PDF 转 Markdown 会生成与 GitHub 兼容的 Markdown：标题、粗体和斜体文字、列表、表格、链接、代码块和引用块会保留；字体、颜色和页面版式会被去掉。在没有表头行的表格中，第一行会成为表头，因为 GFM 表格必须有表头。以数字开头的普通段落（如“1. 条款”）会被转义，以免意外变成列表。文件以无 BOM 的 UTF-8 保存。
常见问题
怎么打开 MD 文件？
任何文本编辑器都能打开。要查看排版效果，可以使用 Visual Studio Code 的预览或 Markdown 编辑器；如果想在 Word 中阅读，请把它转换为 DOCX。
CommonMark 和 GitHub Flavored Markdown 有什么区别？
CommonMark 用精确的规则定义了 Markdown 的核心语法。GFM 是它的超集，在 CommonMark 之上加入了表格、任务列表、删除线和扩展自动链接等扩展。
Markdown 能做表格吗？
可以，借助 GFM 等扩展，你可以用竖线和连字符写出简单的表格。对于合并单元格等复杂结构，请使用 HTML 表格，或在 Word 中制作文档。
Markdown 和 HTML 有什么区别？
Markdown 是一种更简单的写作格式，设计目的就是被转换成 HTML。它无法表达 HTML 能表达的所有内容，但原始形式的可读性要高得多。需要时，你仍然可以在 Markdown 中直接写 HTML。
Markdown 有官方标准吗？
Gruber 最初的说明并不是正式规范。如今最广泛接受的精确定义是 CommonMark，而 text/markdown 媒体类型由 2016 年 3 月的 RFC 7763 注册。
