CommonMark 规范要点解读

本贴最后更新于 1613 天前,其中的信息可能已经沧海桑田

为什么需要 Markdown 规范

CommonMark 规范开篇就提到了这个问题,并列举了十多个例子来说明制定一个 Markdown 规范的必要性。

由于没有明确的规范,Markdown 解析渲染会有很大差异。因此用户经常会发现在一个系统(例如 GitHub)上渲染正常的文档在另一个系统上渲染不正常。更糟糕的是由于 Markdown 中不存在“语法错误”,所以无法立即发现这类问题。

在 Markdown 处理上“模糊的正确”是不可取的。所以 CommonMark 规范的目的就是消除二义性,制定统一明确的 Markdown 解析渲染规则。

作者阵容

CommonMark 规范的主创 John MacFarlanejgm)是加州大学伯克利分校的哲学教授,他在文本标记语言领域有一个很出名的项目 Pandoc(用于在各种文本标记语言之间互转格式)。他用多种编程语言实现过 Markdown 引擎,在 Markdown 处理方面他可以称得上行家中的行家。

该规范的其他参与者包括:

  • David Greenspan, 来自 Meteor
  • Vicent Marti, 来自 GitHub
  • Neil Williams, 来自 Reddit
  • Benjamin Dumke-von der Ehe, 来自 Stack Exchange
  • Jeff Atwood, 前 Stack Exchange 联合创始人,Discourse 创始人

从作者阵容我们可以看出,该规范算是众望所归了,因为这几大社区都需要一个标准化的 Markdown。

除了强大的作者阵容外,最重要的是规范的严谨度我相信不会有任何问题,600+ 测试用例也尽量将各种情况都列举验证了,整体的权威性毋庸置疑。

介绍完大致背景,下面我们进入技术细节,对规范中定义的要点进行解读。

元素分类

为了方便解析,将内容元素分为块级元素和行级元素,其中块级元素又分为两类:

  • 容器块:可包含其他块级元素,只有 3 种容器块:块引用(>)、列表项和列表(列表只能包含列表项)
  • 叶子块:不能包含其他块级元素,只能包含行级元素。比如分隔线、标题、代码块、某些 HTML 块、段落等

行级元素包括:内联代码(`code`)、强调、加粗、链接、图片、某些 HTML 标签、文本等。

优先级

  • 块级元素解析优先级永远高于行级元素(先生成块级元素后生成行级元素)
  • 行级元素中 HTML 标签和自动链接的优先级最高,Code Span 次之
  • Setext 标题优先级高于分隔线。比如如下示例
    Foo
    ---
    bar
    
    将生成
    <h2>Foo</h2>
    <p>bar</p>
    
  • 分隔线优先级高于列表项
  • 缩进如果出现在列表项中,以列表项对齐优先(不解析为缩进代码块)。比如如下示例
      - foo(f 之前是 2 个空格、1 个 - 然后再加 1 个空格)
        bar(b 之前是 4 个空格)
    
    将生成
    <ul>
    <li>foo
    bar</li>
    </ul>
    
  • 强调分隔( *_)出现嵌套情况时,优先第一个。比如 *foo _bar* baz_ 将生成 <em>foo _bar</em> baz_ 而不是生成 *foo <em>bar* baz</em>
  • 出现多个可结束的强调分隔符时,以后打开的分隔符优先。比如 **foo **bar baz** 将生成 **foo <strong>bar baz</strong> 而不是生成 <strong>foo **bar baz</strong>
  • 链接文本(link-text)优先级高于强调:*[foo*](/uri) 将生成 <p>*<a href="/uri">foo*</a></p>

具体场景细节可在规范中搜索关键字 precedence

段落分段规则

某些情况下不需要空行即可“打断”当前内容,形成新的段落或者其他块级元素。

  • 专题分隔线 *** 打断段落
  • ATX 标题 # h 打断段落,Setext 标题不打断,需要用空行分隔之前的内容
  • 围栏代码块 ``` 打断段落
  • 大部分 HTML 标签可打断段落,除了带属性的,比如 <a <img
  • 块引用 > 打断段落
  • 第一个非空列表项打断段落(即新列表打断段落)

每种情况的细节可以到规范中搜索关键字 interrupt

段落延续文本

段落延续文本(Paragraph continuation text)即段落开始后不被分段规则打断的部分,该部分也算作当前段落。

最简单的例子是以 \n 分隔的两行文本:

foo
bar

渲染的 HTML 结果应该是:

<p>foo
bar</p>

在其他元素中的例子:

> foo
bar

渲染的 HTML 结果应该是:

<blockquote>
<p>foo
bar</p>
</blockquote>

强调和加粗

分隔符序列(delimiter run):

  • 由一个或多个非 \ 转义的 * 构成或者
  • 由一个或多个非 \ 转义的 _ 构成

左侧分隔符序列(left-flanking delimiter run):

  1. 是一个分隔符序列
  2. 后面不能跟空白
  3. 后面不能跟标点;或者后面跟标点并且前面是空白或者标点

右侧分隔符序列(right-flanking delimiter run):

  1. 是一个分隔符序列
  2. 前面不能是空白
  3. 前面不能是标点;或者前面是标点并且后面是空白或者标点

解析策略参考

规范附录部分介绍了一种解析策略,总的来说分为两个阶段:

  1. 将输入文本断行,顺序解析每一行并生成块级节点。文本作为块级节点的内容,暂时不进行解析。链接引用定义在这个阶段也会被解析构造放到一个 Map 中
  2. 解析每个块级节点的内容生成行级节点。如果有引用定义的话使用阶段 1 中的 Map 进行解析

举个例子,对于给定的 Markdown 文本:

## 简介

一款 *Markdown* 引擎。

## 特性

* 实现 _GFM_
* 非常快

生成 Markdown 语法树为:

{ "title": { "text": "Markdown 语法树示例" }, "tooltip": { "trigger": "item", "triggerOn": "mousemove" }, "toolbox": { "show": true, "feature": { "mark": { "show": true }, "restore": { "show": true }, "saveAsImage": { "show": true } } }, "calculable": false, "series": [ { "name": "树图", "type": "tree", "symbolSize": 10, "initialTreeDepth": -1, "roam": true, "left": 0, "right": 0, "orient": "vertical", "label": { "position": "top", "verticalAlign": "middle", "align": "left", "fontSize": 12, "offset": [9, 12] }, "lineStyle": { "color": "#4285f4", "shadowBlur": 8, "shadowOffsetX": 3, "shadowOffsetY": 5, "type": "curve" }, "data": [ { "name": "Document", "children": [ { "name": "Heading\nh2", "children": [ { "name": "Text\n'简介'" } ] }, { "name": "Paragraph\np", "children": [ { "name": "Text\n'一款'" }, { "name": "Emph\nem", "children": [ { "name": "Text\n'Markdown'" } ] }, { "name": "Text\n'引擎'" } ] }, { "name": "Heading\nh2", "children": [ { "name": "Text\n'特性'" } ] }, { "name": "List\nul", "children": [ { "name": "Item\nli", "children": [{"name": "Paragrap\np", "children": [{"name": "Text\n'实现'"},{"name": "Emph\nem", "children": [{"name": "Text\n'GFM'"}]}]}] }, { "name": "Item\nli", "children": [{"name": "Paragrap\np", "children": [{"name": "Text\n'非常快'"}]}] } ] } ] } ] } ] }

下面介绍强调和链接解析处理,这部分比较有技巧。

嵌套强调和链接的解析算法

强调、加粗、链接、图片这四种节点都是行级元素,但这四种元素的解析生成稍微有点麻烦,因为它们有可能存在嵌套。建议结合 CommonM 官方参考实现 JavaScript 版的文件 inlines.js 来看就容易理解了(注意该实现进行了一定优化,比如去掉了 current_position 变量,但总体逻辑没有变)。

解析行级元素时,如果遇到:

  • 一系列 *_ 字符,或者
  • 一个 [![

时,则以这些符号作为文本内容生成一个文本节点,并在分隔符栈(delimiter stack)中压入一个指向该文本节点的元素。

分隔符栈是一个双向链表,其中每个元素都指向一个文本节点,并附加如下信息:

  • 分隔符类型([![*_
  • 分隔符数量,比如强调是 1 个 *,加粗则为 2
  • 分隔符是否处于“激活”状态(开始解析时都是激活状态)
  • 分隔符是否是一个开始分隔符、结束分隔符或者两者都可能(这取决于分隔符前后的字符序列)

当我们解析时遇到 ],则进入下面介绍的链接和图片处理过程

当我们解析到输入结束时,则将 stack_bottom 置为 NULL 并进入下面介绍的强调处理过程

链接和图片处理过程

从分隔符栈顶部开始回看寻找开始的 [ 或者 ![ 分隔符元素。

  • 如果没有找到,则返回一个文本节点 ]
  • 如果找到了,但这个元素处于非激活状态,则从栈中移除该元素,然后返回一个文本节点 ]
  • 如果找到了,并且这个元素是激活的,则我们继续解析看是否能构成一个内联链接/图片、引用链接/图片、紧凑链接/图片或者快捷链接/图片
    • 如果不能,则从栈中移除这个开始分隔符,然后返回一个文本节点 ]
    • 如果能,则执行如下步骤
      • 生成一个链接或图片节点,其子元素为开始分隔符指向的文本节点之后的行级元素
      • 在这些行级元素上以开始分隔符 [ 作为 stack_bottom 执行强调处理过程
      • 从栈中移除该开始分隔符
      • 如果是链接(不是图片),则设置所有位于该开始分隔符之前的 [非激活状态(防止链接嵌套链接)

强调处理过程

参数 stack_bottom 设置了分隔符栈的栈底下限。如果其值为 NULL 则我们可以一直遍历到栈底。否则我们应该在访问到 stack_bottom 之前停止。

current_position 指向分隔符栈中高于 stack_bottom 的元素(当 stack_bottom 为 NULL 时指向第一个元素)。

使用 openers_bottom 来跟踪每种分隔符(按类型 *_ 和结束分隔符长度模 3)。初始化值为 stack_bottom

然后我们重复以下步骤,直到用完了潜在的结束分隔符:

  • 在分隔符栈中向前移动 current_position 直到找到第一个潜在的结束分隔符 *_。(这是离开始最近的结束分隔符 —— 也是按解析顺序的第一个)
  • 现在我们向回查找(查找位置高于 stack_bottom 以及相应的 openers_bottom )第一个匹配的开始分隔符(“匹配”的意思是和结束分隔符一样的分隔符)。
  • 如果找到了:
    • 需要弄清楚是强调还是加粗:如果开始符和结束符的长度都 >=2,则是加粗,否则是普通强调
    • 在开始分隔符指向的文本节点后面插入一个 em 或者 strong 节点
    • 从分隔符栈中移除所有位于开始符和结束符之间的分隔符
    • 从开始和结束文本节点中移除 1 个(对于普通强调)或者 2 个(对于加粗)分隔符。如果它们为空了,则移除它们,并从分隔符栈中也进行移除。如果结束符节点被移除,则设置 current_position 为栈中的下一个元素
  • 如果没有找到:
    • 设置 openers_bottom 指向 current_position 前的元素。(此时我们知道该结束符没有对应的开始符,所以需要更新下限以便用于将来的搜索)
    • 如果 current_position 指向的结束符不是一个潜在的开始符,则将它从分隔符栈中移除(因为它既不是开始符也不是结束符)
    • current_position 移动到栈中的下一个元素

处理完后,我们从分隔符栈中移除了位于 stack_bottom 之上的所有分隔符。

1 操作
88250 在 2019-10-29 17:26:09 更新了该帖

相关帖子

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...
  • 😳 学习下 虽然就瞄了几行

  • 其他回帖
  • 88250

    Vditor 编辑器支持的,可参考这里 https://hacpai.com/guide/markdown

  • cmlanche

    文章中是怎么嵌入的这个 markdown 文档树的?

    1 回复
  • darren

    文档写得非常棒 👍

    不过文档中是不是用的版本比较旧了,试了下最新版本的 vidtor,渲染出来的结构树没有问题

    文档中的 最新版本 Vditor 渲染出来的
    old.jpg echarts.png

    希望能更新一下下

    我不是强迫症……我真的不是强迫症……我就是看着不舒服而已……

    1 回复
  • 查看全部回帖