转载

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

修复 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 注释就可以了。

不用谢。

相关阅读

  • [译] GitHub 风格的 Markdown 语法
  • [译] GitHub 上的书写方式

本文在 “CSS魔法” 微信公众号首发,扫码立即订阅:

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

© Creative Commons BY-NC-ND 4.0   | 我要订阅 |   我要打赏

原文  https://github.com/cssmagic/blog/issues/70
正文到此结束
Loading...