Markdown 是一种轻量级标记语言,用于以纯文本编写结构化文档。它由约翰·格鲁伯于 2004 年推出,亚伦·斯沃茨也为其设计提供了大量意见。Markdown 使用基于标点符号的约定来表示标题、列表、强调、链接等文档元素,并配有转换程序,最初用于生成超文本标记语言。其核心设计目标是让源文本无需渲染也能保持可读:Markdown 文档应当像普通的文本文档,而不是充斥着格式指令的页面。
Markdown 这一名称既指格鲁伯最初设计的语法及转换程序,也泛指一系列相关格式。Markdown 广泛用于软件文档、项目自述文件、技术出版物、讨论平台和个人笔记。后来的规范和实现,尤其是 CommonMark 和 GitHub 风格的 Markdown,澄清了含糊的规则,并增添了新功能。因此,要理解 Markdown,就需要区分各类格式共有的约定,以及具体解析器、扩展和发布系统的处理方式。
起源与设计原则
约翰·格鲁伯于 2004 年 3 月通过他的 Daring Fireball 网站发布了 Markdown。最初发布的内容包括语法说明和一个用 Perl 编写的转换程序,通常称为 Markdown.pl。在开发过程中,亚伦·斯沃茨贡献了想法,并参与测试、提供反馈。最初的软件采用 BSD 风格的许可证发布,允许其他项目将其纳入其中。Markdown 诞生时,博客发布和基于网页的写作工具正蓬勃发展,但作者往往仍需直接编写 HTML。
Markdown 设计的首要目标,是让未经处理的源文本易于阅读。HTML 使用 <p> 和 <em> 等元素明确标记文档结构,而 Markdown 则采用人们熟悉的文本惯例:用空行分隔段落,用星号表示强调,用行首的标点符号标示列表或引用。这些惯例借鉴了电子邮件及其他纯文本交流中已有的做法。因此,即使没有可用的渲染软件,人们仍能在基础文本编辑器、电子邮件或源代码仓库中读懂文档。
Markdown 的设计并非要取代 HTML 的全部功能。最初的语法涵盖了文章写作中常用的结构,同时允许作者在没有对应 Markdown 语法的地方插入 HTML。这使它很适合网页发布:作者可以用简单的文本惯例编写文档的大部分内容,并在需要时加入特定的 HTML。由此形成的语言,介于完全无结构的文本与全面的文档描述系统之间。
Markdown 这个名称是对“markup”(标记)一词的文字游戏,强调的是一种相对不显眼的标记方式,而不是没有结构。Markdown 仍然具有语法、优先级规则,以及因具体实现而异的行为。它看似简单,主要是就写作体验而言;解析嵌套列表、强调分隔符或嵌入的 HTML,可能需要相当复杂的解析器逻辑。
最初的说明也没有完整规定某些语法之间的相互作用。它有效地解释了常见用法,却不是一套能对所有可能输入作出明确规定的形式文法。随着使用不同编程语言编写的独立实现陆续出现,各个实现在处理有歧义的情况时作出了不同选择。易于上手的核心语法、宽松的实现文化与不完整的规范相结合,既推动了 Markdown 的普及,也造成了方言差异,而这些差异后来成为标准化工作要解决的问题。
文档结构与块级语法
Markdown 区分块级结构与行内格式。块级结构包括段落、标题、引用、列表、主题分隔线和代码块。强调、链接等行内元素通常出现在这些块内。这一区分很重要,因为标点符号的含义取决于上下文:位于符合语法要求的行首的星号可能用于引出列表项,而段落内部的星号则可能用于标记强调文本的边界。
段落通常由连续的非空行组成。源文本中的单个换行通常不会产生新段落;段落之间以空行分隔。按照 CommonMark 的术语,段落内的普通换行会产生软换行,其呈现方式可能有所不同。在换行前添加两个空格,或在 CommonMark 中在换行前添加一个反斜杠,就会产生硬换行。有些平台会刻意让普通换行更直接地体现为显示上的换行,尤其是在评论和消息中,因此,同一内容在代码仓库文档和讨论界面中的表现可能不同。
标题主要有两种形式。ATX 标题以一至六个井号开头,井号与标题文字之间需要适当分隔。Setext 标题则在文字下方放置一行等号或连字符,分别形成一级或二级标题。以下示例展示了几种块级结构:
# 安装
下载软件包并解压。
## 要求
- 受支持的操作系统
- 充足的磁盘空间
> 升级前请查看发行说明。
标题级别表达的是层次关系,而非规定的显示大小。标题的实际外观取决于输出所用的渲染器和样式表。
列表可以是无序列表,也可以是有序列表。无序列表通常使用 -、+ 或 *;有序列表则使用数字标记。CommonMark 允许在有序列表的数字后使用英文句点或右圆括号。起始数字可能影响所生成列表的起始编号,但源文本中后续各项的数字不一定决定最终显示的编号顺序。嵌套列表和包含多个段落的列表项取决于缩进和块级结构的延续规则。空行可以区分“紧凑”列表与“松散”列表;在紧凑列表中,列表项内的段落在渲染时不会被包裹在段落元素中。
块引用使用 > 标记,其中可以包含段落、列表或其他引用。主题分隔线由符合语法要求的一行重复星号、连字符或下划线构成。由于一行连字符也可能充当 Setext 标题的下划线,因此其含义取决于上下文。这些相互作用解释了为什么表面上相似的文本可能产生不同的结构:Markdown 解析并非只是若干彼此独立的标点替换操作的集合。
行内格式、链接与字面文本
行内语法为段落、标题及其他容器中的文本赋予结构。星号或下划线通常表示强调,双写的定界符则表示着重强调。这些结构通常会转换为 HTML 的 <em> 和 <strong> 元素,表达的是强调含义,而不只是要求以斜体或粗体显示。定界符的具体行为因方言而异。例如,CommonMark 根据周围的空白字符和标点符号制定规则,以减少单词内部意外出现的强调,并使嵌套组合得到一致的解析。
链接将可见的标签与目标地址组合起来。常见的行内形式是 [标签](目标地址),还可以在括号内的目标地址后附上标题。引用式链接将标签的使用与目标地址的定义分开,便于在正文之外统一管理重复引用或较长的地址。图片使用类似的形式,但以感叹号开头;方括号中的文本提供替代描述,而不是普通的可点击标签。
阅读[安装指南](guide.html)。
查阅[参考手册][manual]。
[manual]: manual.html "参考手册"

引用标签有相应的匹配和规范化规则,比较时不一定要求字节序列完全一致。相对目标地址的解释取决于发布系统提供的上下文。同一份源文档发布到其他位置时,原本在代码仓库查看器中有效的引用可能需要改写。
行内代码使用反引号作为定界符来表示字面文本。定界符可以包含多个反引号,从而允许其中的文本包含较短的反引号序列。行内代码不进行通常的强调和链接解析,因此适合表示标识符、命令和语法示例。其空白字符处理方式由具体方言规定,并不总是逐字保留源文本中的每个字符。较大段的字面文本示例应放在代码块中,而不是行内代码中。
反斜杠转义可使许多标点字符按字面显示,而不发挥通常的结构作用。转义是否生效取决于上下文:在普通正文中可识别的转义,在行内代码中可能没有特殊作用。主流方言也支持在普通文本中使用 & 等字符引用。因此,作者需要区分源文本中写入的字符与解析后生成的文本。
链接和图片体现了文档内容与应用程序行为之间的一条重要界线。Markdown 可以描述目标地址和标签,但它本身并不获取资源、判断目标地址是否安全,也不规定图片的布局方式。这些任务由配套的发布软件、网页浏览器或输出渲染器负责。同样,自动生成标题标识符、设置图片尺寸以及在新窗口中打开链接,也都不是原始语法普遍具备的功能。
解析、渲染与文档模型
Markdown 处理器解释源文本,并生成输出表示形式。最初的程序主要将 Markdown 转换为 HTML,而后来的系统往往将解析与渲染分开。解析器可以构建一棵抽象语法树,其中包含表示段落、标题、列表、文本、链接及其他元素的节点。随后,不同的渲染器可以将这一结构转换为 HTML、其他标记格式,或供出版工具使用的中间表示形式。
许多现代解析器大致分两个阶段工作。块级解析确定文档的整体组织结构,包括哪些行属于列表项、引用块或代码块。随后,行内解析在适用的块内识别强调、行内代码、链接及相关结构。这种划分有助于理清解析时的依赖关系:围栏代码块中的标点不能当作普通正文的语法来处理,而段落中的文本通常仍需接受行内解析。
借助中间树结构,工具无需反复操作原始字符串,就能对文档进行变换。例如,工具可以收集标题以生成目录、改写相对链接、为节点附加源文本位置信息,或检查图像描述。这些操作依赖的是表示文档含义、而非最终视觉外观的数据结构。源文本位置信息对编辑器诊断尤其有用,也有助于将渲染结果与原始文件对应起来。
渲染与样式设置是两个不同的问题。输出的 HTML 可以包含结构正确的标题和列表,但其字体、边距、颜色及响应式行为通常由层叠样式表控制。同样,语法高亮通常也由额外的组件提供。围栏代码块可以在信息字符串中声明所用语言,但 Markdown 解析器本身不必理解该语言,也不必执行语法高亮。
这一处理流程也解释了为什么 Markdown 通常不是一种无损的交换格式。不同的源文本形式可以产生相同的文档结构:用下划线书写的标题,可能与用井号书写的标题等效。一旦处理器只保留解释后的结构,原始的具体写法、空白以及引用式链接的组织方式就可能丢失。因此,格式化工具可能在保留含义的同时,大幅改写源文本。需要在编辑、转换后精确还原原文的系统,则必须采用更丰富的表示形式,以保留语法细节,或将树节点与原始文本关联起来。
输出质量还取决于目标格式。HTML 天然适合承载超链接、流式文本和嵌入式网页内容。分页、浮动插图、带编号的公式以及精细排版,则需要额外的约定或表达能力更强的出版处理层。因此,转换为另一种格式,并不只是将标点替换为标签那么简单。
CommonMark 与标准化
Markdown 早期的成功催生了众多独立实现,但最初的语法说明并未明确所有边界情况。对于嵌套块需要多少空格、分隔符能否在单词内部构成强调,以及一行内容在什么情况下会打断已有段落等问题,不同解析器的处理方式各不相同。作者写出的文档可能在某个应用中显示正常,到了其他应用中却呈现出不同的效果。
CommonMark 于 2014 年公开启动,旨在为广泛采用的 Markdown 核心语法制定一份精确、可测试的规范。约翰·麦克法兰(John MacFarlane)和杰夫·阿特伍德(Jeff Atwood)是其中的重要参与者。该项目最初名为 Standard Markdown,后来改用 CommonMark。其规范并不只是用文字和常见用法示例来说明语法,而是将详细规则与大量输入、输出示例相结合。这些示例也可作为测试用例,用于检验各个实现是否符合规范。
规范处理了一些普通用户可能很少留意、但解析器作者必须解决的细节。它定义了容器块、空行、制表符、列表标记宽度、强调分隔符序列、链接优先级以及原始 HTML 块,还对围栏式代码块作出了正式规定。围栏式代码块不在格鲁伯最初记载的语法之中,但在后来的实现中已得到广泛采用。围栏由一串符合要求的反引号或波浪号组成,结束围栏则须遵循明确的匹配规则。
CommonMark 并不等于“现代 Markdown 应用所支持的全部功能”。表格、任务列表、脚注、参考文献引用和数学记号并非全都属于其核心规范。处理器可以在实现 CommonMark 的同时,另行提供扩展功能。这一区分使核心规范能够充当兼容性基准,同时让应用保留支持专门文档类型的自由。
参考实现包括用 C 编写的 cmark,以及用 JavaScript 编写的 commonmark.js。其他解析器各有自己的架构和扩展系统。是否符合规范,最终取决于对输入的实际解析结果,而不是处理器采用哪种语言实现。
CommonMark 也体现了语言标准化中一种更普遍的矛盾。严格保留历史上每一种解析器的行为,只会保留矛盾,而无法消除矛盾;但改变行为又可能影响已有文档。因此,它的规则代表了对 Markdown 的一种明确定义的解释,并不意味着以往的各种解释原本完全一致。最初的 Markdown 说明、CommonMark 和各平台专用的方言,至今仍是不同的参照依据。明确说明工具实现的是哪一种,比仅仅声称它“兼容 Markdown”更有意义。
方言与扩展
Markdown 方言将核心语法与一套特定的扩展和解释规则结合起来。有些方言有正式文档说明,另一些则实际上由特定应用程序定义。相似的视觉形式可能掩盖实质性的差异。在某个平台的用户看来,表格、脚注或数学表达式可能都是普通的 Markdown,而在另一个平台中,它们却仍然只是纯文本。
GitHub Flavored Markdown(通常缩写为 GFM)是一个典型例子。GitHub 于 2017 年发布了基于 CommonMark 的正式规范。规范定义的扩展包括表格、任务列表项、删除线、扩展的自动链接识别,以及对某些原始 HTML 结构的过滤。[ ] 或 [x] 这样的任务列表标记出现在适当的列表上下文中时,可以显示为类似复选框的形式。复选框能否交互,取决于承载文档的应用程序,而不只是语法本身。
GFM 表格使用竖线分隔单元格,并用分隔行区分表头与数据。分隔行中的冒号可以指定对齐方式。这种表示法便于呈现紧凑的矩形数据,但无法提供 HTML 表格的全部表达能力:合并单元格和复杂的多级表头通常需要采用其他表示方式。单元格内容过长或包含多行时,也会使纯文本表格难以维护。
其他 Markdown 分支则因不同用途而产生。Markdown Extra 增加了表格、定义列表和脚注等功能。MultiMarkdown 为涉及元数据、注释、表格和出版工作流程的文档提供了更丰富的支持。Pandoc 支持一种功能广泛的 Markdown 方言,提供可配置的扩展,以及处理引文、属性和数学内容的功能。MDX 将 Markdown 与 JSX 结合起来,允许文档包含 JavaScript 应用程序中的组件。因此,MDX 不仅改变了可用的语法形式,也改变了发布流程中的执行方式与信任前提。
许多应用程序还在正文语法之外增加了约定。文件开头的元数据块通常称为前置元数据(front matter),可用于定义标题、日期、作者、布局或标签。YAML 是编写此类元数据的常用格式,但前置元数据并不属于原始 Markdown 或 CommonMark。类似地,维基式链接、提示块、图表围栏块和嵌入式查询也都是特定应用程序的功能,除非所选方言对其作出了明确定义。
平台功能也必须与方言功能区分开来。代码仓库中的议题引用、用户提及、上传的附件以及自动生成的导航,可能依赖独立解析器无法获取的应用程序数据。仅复制 Markdown 源文本,并不一定能复现这些功能。因此,可移植性既取决于语法兼容性,也取决于文档所依赖的配套服务是否可用。
编写工具与发布工作流
Markdown 采用纯文本形式,因此适合围绕 Git(版本控制系统)及其他版本控制系统构建的工作流。文档可以与其所描述的软件一同存储,在同一个变更请求中接受审查,并随相关代码一起更新。文本差异能够清楚呈现哪些字词和行发生了变化,而不像二进制文档的修订那样难以辨识。因此,Markdown 在“文档即代码”的文档编写方法中发挥了尤为重要的作用。
代码仓库中最常见的例子是 README.md 文件。托管服务通常会自动渲染该文件,将其作为项目介绍。类似的文件还用于记录贡献流程、版本发布历史和开发笔记。这些惯例并非由 Markdown 规定,但它入门门槛低、源文件易读,恰好适合这些用途。贡献者只需使用普通编辑器就能做些小修改,无须使用原作者的发布应用程序。
静态网站生成器将这一模式扩展到了完整的网站。Jekyll、Hugo 和 MkDocs 等系统将源文档与导航规则、模板和样式表结合,生成可部署的文件。元数据可以控制页面标题或排列顺序,主题则负责视觉设计。在这种安排下,Markdown 描述了页面的大部分内容,但 URL 构建、资源复制和导航等重要行为由生成器决定。
发布流水线通常包含自动化检查。格式检查工具可以识别不一致的标题样式、可疑的缩进,或容易伴随错误出现的格式模式。其他独立的检查则可以验证内部链接、检测缺失文件,或测试代码示例。这些功能不能相互替代:文档即使语法有效,也可能包含失效的链接目标或不准确的命令。与持续交付集成后,文档变更便可触发预览构建和发布,其方式与软件变更触发测试和部署大致相同。
编辑器的形式多种多样,从简单的文本应用程序,到带有实时预览功能的分栏编辑环境,不一而足。有些编辑器提供类似富文本的编辑体验,底层仍以 Markdown 存储。后一种方式可以隐藏语法细节,但对于在源文件中有多种等价写法的结构,编辑器必须决定采用哪种形式。因此,在源码模式和可视化模式之间切换时,可能会统一格式,或重写文件的某些部分。
Markdown 还用于计算笔记本、学习材料和技术书籍。笔记本可以将文本单元格与可执行代码及其输出并列放置,而图书出版流水线则可以整合章节、引文和交叉引用。这些应用体现了 Markdown 作为轻量级编写方式的价值,但其中更丰富的功能来自笔记本或出版系统,而非 Markdown 本身。
安全性、无障碍与国际化文本
Markdown 源码虽然是文本,但渲染后的 Markdown 并不天然安全。处理器可能会将嵌入的 HTML 原样传递到输出中,链接或图像也可能引用外部资源。当内容来自不可信的作者时,发布系统必须区分解析与 HTML 净化。解析决定源码的含义;净化则限制解析结果中允许使用哪些元素、属性和目标地址。
一项主要风险是跨站脚本攻击,即恶意内容导致脚本在其他用户的浏览上下文中执行。仅过滤 Markdown 标点符号,无法堵住所有产生不安全输出的途径。安全边界可能需要考虑原始 HTML、危险的 URL 方案、事件处理程序属性,以及插件引入的变化。对字面文本进行转义、验证目标地址,以及净化生成的 HTML,分别解决这一问题的不同方面。
当扩展能够执行代码时,信任模型还会进一步变化。围栏式代码块通常只用于显示文本,但笔记本或发布插件可能会将某些代码块解释为可执行指令。MDX 可能涉及 JavaScript 组件,而图表或模板扩展会调用额外的处理器。这类文档不能仅作为被动的 Markdown 内容来评估。如何处理它们,属于外围系统的网络安全设计范畴,可能需要限制其能力或使用沙箱。
无障碍性取决于作者如何使用文档结构,以及渲染器如何呈现这些结构。真正的标题能为辅助技术提供导航标志;仅在视觉上放大文字则未必能做到这一点。图像描述应传达图像的相关信息或功能,但基本的 Markdown 图像语法无法提供复杂图形所需的全部无障碍功能。同样,竖线表格语法也未必能够表达复杂的表头关系。对于要求更高的文档,可能需要补充 HTML 或使用额外的发布功能。
Markdown 通常使用 Unicode统一码文本,因此既能用多种文字系统书写正文,又能保留主要取自美国信息交换标准代码的标点式语法。格式本身并未规定所有文件编码或显示约定;应用程序通常使用 UTF-8。全角标点和外观相近的字符一般不能与语法字符互换。因此,编辑器的字体排印方式可能使语法上的差异难以辨认。
国际化发布还会带来更多应用层面的问题。从右向左书写的文本、混合书写方向的链接、换行、语言元数据以及标题标识符的生成,都可能需要核心语法之外的支持。两个渲染器可能都能正确显示同一个多语言标题,却为指向该标题的链接生成不同的片段标识符。即使正文内容得以保留,这种行为仍会影响导航。
可移植性与表达能力的局限
Markdown 的可移植性有几种不同的含义。源文件可移植性是指文件可以在多种工具中打开和阅读。语法可移植性是指不同解析器能够识别相同的结构。呈现可移植性是指生成的文档具有相似的外观。Markdown 在第一方面表现出色,第二方面则取决于更多条件,而第三方面的能力在设计上就受到有意限制。纯文本文件可以独立于特定编辑器而保存,但其渲染结果仍然取决于所用的方言、配置、样式和资源文件。
.md 和 .markdown 是广泛使用的文件扩展名,但两者都无法标明确切的语法规范。RFC 7763 于 2016 年注册了 text/markdown 媒体类型,配套的 RFC 7764 则讨论了各种变体及处理实践。这些文档承认,“Markdown”涵盖多种不同的诠释。媒体类型可以较为可靠地标识大致格式,却不能保证文件中使用的每一种扩展都能得到支持。
因此,要让发布结果可复现,仅保留源文件还不够。项目可能还需要记录解析器版本、已启用的扩展、模板、样式表以及资源文件的位置。即使可见的标题没有变化,标题标识符生成方式的改变也可能使指向这些标题的链接失效。语法高亮功能的更新可能改变生成的标记。远程图片可能已经消失,而指向它的 Markdown 引用仍完好无损。这些都是已发布文档的依赖问题,并非仅靠纯文本存储就能避免的缺陷。
与 HTML 相比,Markdown 提供的显式控制手段较少,编写时使用的标记也更为简洁。与 LaTeX 相比,它通常缺少同等丰富的内置机制来支持数学排版、交叉引用和精确的页面编排。与结构化的 XML 词汇集相比,它对文档组织方式的约束通常更少。这些差异体现了不同的设计侧重点:Markdown 注重让文字写作易于上手,而更复杂的格式则能够表达更丰富的语义和出版要求。
这种简洁也意味着表达能力上的取舍。带有结构化图注的插图、复杂表格、索引、条件性内容,以及详尽的学术注释与参考资料体系,通常都依赖扩展或外部工具。将这样的文档转换为另一种 Markdown 方言时,即使两种系统都支持标题和链接,也可能丢失信息。经由 HTML 进行转换,同样可能丢失对源应用程序有意义的区分。
因此,长期维护需要明确哪些信息存在于文本中,哪些信息存放在别处。段落和普通列表基本上是自成一体的;可执行图表、代码仓库特有的提及标记或动态生成的参考文献表则不然。一份材料究竟是可直接阅读的文档,还是依赖应用程序的发布源文件,取决于实际使用的功能,而不只是 .md 扩展名。