cssmagic commented 7 years ago

修复 Markdown 块引用在 GitHub 显示不连续的问题

问题

不久前 GitHub 更新了它的 Markdown 渲染引擎，对 “块引用”（blockquote）的渲染行为发生了变化。你会发现原先一个完整的块引用会被拆散成多个。

举例来说，假设你写了以下一段 Markdown 文字：

> paragraph 1.

> paragraph 2.

以前会渲染成这样：

paragraph 1.

paragraph 2.

但现在会渲染为两个分离的块引用：

paragraph 1.

paragraph 2.

如果你想得到原来的效果，需要显式地在两个段落之间的空行写一个 >。也就是说，需要写成下面这样，以表明这是一个连续的块引用：

> paragraph 1.
>
> paragraph 2.

修复

首先，我们当然可以给 GitHub 提 issue。但这个过程太慢了，人家也未必会改，而你的文章在此时此刻就需要正确地显示啊，对不对？

所以我们只能 “修复” 自己的文章。手工修复不现实，还是要让工具来搞定。

我写了一个简单的 JS 函数，可以给 Markdown 代码自动补上需要的 >：

function fix(markdown) {
    const src = /^>(.*)\n(?:\s*)\n>/gm
    const dest = '>$1\n>\n>'
    return markdown
        .replace(src, dest)
        .replace(src, dest)
}

（注：这个函数的功能并不完善，无法处理嵌套或缩进的块引用。不过好在实际写作中这类复杂情况并不多。）

如果你有一批文件需要处理，那也只需要把这个函数包装成一个简单的 Node.js 脚本或 Gulp 脚本就可以了。

思考

好，问题解决了，我们来扯点别的。

作为一名资深的 “Markdown 工程师”，我不禁陷入深深的思考：GitHub 为什么要这样改？这是一个 bug 还是 feature？很遗憾，我在 GitHub 的官方文档中并没有找到关于这个变更的记载。

如果这是一个 feature 的话，那么 GitHub 的用意应该是让写作者可以清晰地表达块引用的合并和分割。但是，我认为引入这个变更实际上弊大于利：

这不仅进一步拉大了 “GitHub 风格的 Markdown”（GFM）与标准 Markdown 语法的差异，也拉大了它与其它 Markdown 引擎之间的行为差异。“冒天下之大不韪” 说的就是这种行为。
很多 Markdown 编辑器并不会在块引用的空行处插入 > 标记。这意味着写作者可能需要手工维护这些该死的 >。
破坏了 Markdown 语法的一致性。比如，对于列表来说，在列表项之间插入空行并不会导致列表被分割开。
最重要的是，这个变更并无必要！因为，如果我需要把一个块引用拆开的话，只需要在分割点插入一行 HTML 注释就可以了。比如以下代码在任何 Markdown 引擎中都可以得到一致的（块引用被打断为两个的）效果：
```
> paragraph 1.



> paragraph 2.
```

福利

好吧，我刚刚一不小心又泄漏了一个超级实用的 Markdown 技巧——如果你需要把多个连续的列表项拆分为两个列表的话，插入一行 HTML 注释就可以了。

不用谢。

cssmagic / blog

修复 Markdown 块引用在 GitHub 显示不连续的问题 #70

修复 Markdown 块引用在 GitHub 显示不连续的问题

问题

修复

思考

福利

相关阅读