我们要切换到CommonMark

我是Ham，我是Stack Overflow团队团队的一名开发人员。在过去的几个月中，我一直在努力在网络上撰写和编辑帖子时将Markdown转换为HTML。我很想分享自己的想法。
简而言之：我们正计划在整个网络上的所有帖子中使用CommonMark。为此，我们在客户端和服务器端切换到兼容CommonMark的Markdown渲染器。我们必须确保所有现有帖子都可以与新渲染器一起使用，因此我们将在网络上进行大规模迁移，将现有帖子转换为使用新的CommonMark格式。更改后的写作，编辑和阅读帖子的外观和感觉应该大致相同。
截至2020年6月20日，所有站点现在都位于CommonMark上。对于单个站点，请参阅此处的迁移时间表。

我们在整个Stack Exchange网络中使用Markdown。当Jeff和Joel开始构建Stack Overflow时，Markdown是早期的技术赌注之一。如果您在Stack Exchange网络上的任何地方写下问题，答案或评论，就会在Markdown中编写。
多年来，Markdown已经成为在线社区中编写内容的一种常见方式。它已经取得了巨大的成功，甚至获得了CommonMark的正式规范。
今天，Stack Exchange处理用户创建的Markdown的方法与开始时的方法基本相同。我们在客户端和服务器端使用了自己的本地Markdown解析器和渲染器。事实证明，这两种实现都是坚实的基础，并且多年来进行了许多调整。
但是，它们带有自己的怪癖。它们是在出现CommonMark规范之前创建的，它们显示出一些不符合规范的行为。他们正在使用正则表达式将Markdown转换为HTML（多年来，这让我们付出了很多汗水和眼泪）这是完全可行的，但要维护Markdown解析器并为其添加新功能会更加困难。
想法
我们认为是时候向前迈进了。您曾经问过我们几年前是否要在Stack Exchange网络上采用CommonMark，balpha进行了统计，尽管他发现并非不可能，但似乎并不容易，要么。鉴于过去和即将发生的一些变化，我们认为现在是解决这一挑战并将所有网络帖子迁移到CommonMark的好时机。这包括：

在客户端上更改Markdown渲染器
在服务器上更改Markdown渲染器
自动编辑并重新呈现网络中非CommonMark的所有帖子-compatible

要使您对幕后的变化有更好的感觉：在Stack Exchange网络上撰写文章时，请在Markdown中编写。在客户端，您在撰写文章时会看到预览。此预览由我们的客户端Markdown渲染器创建。它使用您编写的Markdown，将其转换为HTML，并向您显示帖子的外观。
保存帖子后，我们会将Markdown发送到我们的服务器，在其中，相同的Markdown-to-HTML转换再次发生（您不能信任用户输入，因此我们不会盲目接受客户端生成的HTML）。
我们的计划
我们将通过网络将网站迁移到CommonMark网站在接下来的几周内按站点进行。我们计划从2020年6月3日（星期三）开始进行元堆栈交换和元堆栈溢出。
我已经准备好了一项功能，该功能可以将我们当前的本地Markdown渲染器与经过测试的，遵循CommonMark规范的开源实现交换。出于好奇：这意味着我们将在客户端将PageDown替换为markdown-it，在服务器端将MarkdownSharp替换为markdig。
一旦启用此功能，新的和已编辑的帖子将自动使用这些新的渲染器进行渲染。 。最有可能的是，您在看帖子时甚至都不会发现差异。对于网络中的绝大多数帖子（80％或以上），这意味着什么都不会改变。是的，我们网络上的大多数帖子都是按照完全符合CommonMark规范的方式编写的，是的！如果我们使用新的渲染器将此Markdown转换为HTML，结果将完全相同。期望。 Balpha的分析为您提供了更多详细信息。我们谈论的是在哈希和其他一些小的疏忽之后再加上空格的##headlines。对于这些帖子，我们构建了一个工具，可通过直接更改帖子的Markdown来源并重新呈现相关帖子的HTML来自动解决这些众所周知的问题。当我们自动更改帖子的Markdown时，最终看起来像是常规编辑，但是我们确保这不会使帖子升到顶部。
所以现在我们大约有80％的帖子那已经很好了。借助自动修复实用程序，我们估计在迁移到CommonMark并使用新的渲染器后，渲染的所有网络帖子中将有96％以上完全相同。这给我们留下了百分之几的帖子，当使用新的CommonMark渲染器进行渲染时，它们最终看起来会有所不同。
您可以期待的是什么
我们会出于安全方面的考虑而避免破坏现有职位。如果使用新的渲染器发布的帖子看起来有所不同（并且只有一个空白），我们将不会自动重新渲染该帖子并将其首先放置以进行调查。这样我们就可以确保所有更改都是安全的。
我一直在处理我们的数据，以感觉使用新渲染器后渲染的帖子会稍有不同。我发现差异分为三个部分：


误报：HTML标记略有更改，但不更改帖子的语义或表示形式

改进：CommonMark规范解决了我们当前Markdown风格中的一些疏忽的问题

实际问题：我们没有想到并需要修复的问题

“实际问题”类别应该只占很小的一部分，但我不会天真地假设它们不会发生。我们需要研究由新的Markdown渲染器引起的一些变化，因为它们会使帖子以一种或另一种方式看起来与以前有所不同。我们无法预见此更改将引入的所有极端情况，因此我们将浮出所有使用新的Markdown渲染器渲染时看起来不同的帖子，对其进行审查，并在必要时进行修复。尽可能平滑无摩擦。我们不想破坏（并手动修复！）成千上万的帖子。我们不想弄乱您的写作经验。同时，我知道我们从一开始就不会完美使用此功能，因此我需要您的耐心和谅解。
当我们切换到新的CommonMark渲染器后撰写新文章时，您将拥有与以前完全相同的书写体验。预览将向您显示您的帖子的外观，并且一旦保存您的帖子，其外观应与您在预览中看到的一样。如果您发现预览和保存的帖子之间有任何差异，请通知我们！
当您编辑用新的CommonMark渲染器渲染的帖子时，事情可能会变得很时髦。同样，如果我们在迁移过程中检测到帖子在使用新的CommonMark渲染器进行渲染时看起来会有所不同，则不会在迁移过程中保存该帖子的新版本。这样，所有帖子在查看时仍会保持相同的外观。但是，一旦有人进入并对其进行编辑，它将使用新的CommonMark渲染器进行渲染，这可能导致帖子的外观与我们之前的外观略有不同。这只是我们所有职位的一小部分，而在那一小部分中，实际上会编辑一小部分。但是，请务必记住，编辑旧帖子有一点机会，您会遇到我们的旧Markdown渲染器与新Markdown渲染器之间的差异。

常见问题解答
什么时候
新的CommonMark渲染器将在接下来的几天内合并为master。它们被隐藏在功能标记的后面，因此在我们按下开关之前不会造成任何伤害。
我们将在接下来的几周内逐个站点地跨网络迁移站点。我们将从2020年6月3日（星期三）开始进行元堆栈交换和元堆栈溢出（假设一切顺利，并且直到那时我们都不会发现主要的阻塞程序）。由于我们无法准确预测沿途会遇到哪种龙，因此计划可能会稍有变化。我将发布站点计划及其切换日期，以解答该问题，并在我们进行更新时保持更新。
每个站点都是不同的，我们需要不断学习。大多数站点可以在几个小时内迁移。对于我们最大的网站，将所有帖子更改为CommonMark可能最多需要4天。请留意我要发布的进度表。
我们为什么要迁移到CommonMark？
过去，对Markdown渲染器的更改相当冒险且费力。我们需要仔细评估更改是否对我们现有的数百万个现有职位没有任何影响。通过遵循定义良好的规范（如CommonMark），我们可以确保遵循该规范的实现对我们有用。如果规范得到扩展，则采用更改将变得容易且安全。
另一个原因是，这减轻了我们开发团队的一些维护负担。现在，我们无需维护两个不同的Markdown渲染器，而是可以直接使用现成的东西。使用markdig和markdown-it，我们发现了两个著名的库，它们在性能和功能方面都超过了我们自己的实现。两者都是很棒的软件，我们非常乐意在产品中使用。
以后我编写Markdown的方式是否有所变化？
是的，会有一些变化到Stack Exchange上支持的Markdown集合。在您的大部分写作中，您根本不会发现任何区别。我们将尽最大努力继续允许您现在使用的大多数语法。我们采用的是CommonMark标准，因此所有有效的CommonMark都可以在Stack Exchange上正常使用（以下是简短的备忘单，以示好奇）。
同时，我们希望借此机会消除在没有CommonMark标准之类的情况下建立的一些怪癖。 Stack Exchange当前Markdown风格的某些功能是在没有标准化的处理方式的时候构建的。现在，我们正在采用CommonMark，我们想用标准化的符号替换一些本地开发的功能，您也可以从网络上的其他地方知道这种符号。
最明显的变化将是嵌套在列表周围列表，标题和块引号。
列表：
创建嵌套列表时，需要缩进嵌套列表项或段落的空格数量。虽然以前一个空格就足够了，但是根据列表的类型，您现在需要再添加几个空格。
要使段落成为列表项的一部分，它过去足以在列表的前面添加一个空格该段落

* this is a list item

 that goes on here

和CommonMark一起，该段落必须与父文本对齐，因此我们在这里需要一些空格：

* this is a list item

  that goes on here

标题：
向前移动，必须在前导#字符后添加一个空格。

#this was cool before

# this is what's cool now

块引用：块引用。继续前进，您将以这种方式获得两个不同的块引用，除非您也以>字符开头空行：最大的突破性变化将围绕缩进的代码块，以及声明用于语法高亮显示的语言的可能性。围栏符号和不缩进的代码块。您仍然可以使用缩进的代码块，但是以后不再支持为它们明确声明首选语言。
到目前为止，您可以执行以下操作来声明缩进代码块的语言：

> old blockquotes  

> with multiple lines

向前移动，此样式被认为已弃用。自从我们引入了代码围栏以来，您就可以使用代码围栏符号显式声明代码块的语言：

> new blockquotes
> 
> with multiple lines

这是CommonMark标准提出的方式，而这也是其他网站的目的也是。我们知道您可能已经习惯使用带有<!-- language: lang -->注释的旧语法。当我们采用新的Markdown解析器时，我们希望避免以一种正式的，符合标准的方法来实现将那些古怪的行为修补到这些解析器中，而我们可以毫不费力地采用它。此样式暂时仍会继续起作用，但是将来可能会被删除，此时使用该样式的帖子将不再识别它。
请注意，根据您使用的标签设置语法突出显示语言与您的帖子关联的内容将继续起作用。如果您需要刷新，这里是我们语法突出显示当前行为的完整概述。我们将在前进的同时更新该帖子。
SE专用语法元素会发生什么情况？
在Stack Exchange网络上，我们支持不属于CommonMark标准的某些语法元素。扰流器，MathJax，电路图，堆栈片段等内容在多个网络站点上使用。即使它们不是正式的CommonMark规范的一部分，我们也将继续支持所有这些自定义语法元素。
这最终将启用表支持吗？
也许！过去已经对表格的支持进行了激烈的讨论。有很多创造性的解决方法，但是从来没有任何官方支持渲染表。如果其他网站可以做到这一点，为什么不能呢？
主要原因之一是我们的Markdown解析器和渲染器不支持表格这一事实，由于我们切换到Markdig和Markdown-it，现在不再有效。两者都支持开箱即用地解析和呈现表。尽管如此，引入表支持仍然是我们不希望盲目地迁移到这种大型迁移中的一种变化。规格这种变化是巨大的。我们需要查看效果如何，并确保在我们所有社区中都不会引入超过几个可接受的外观设计问题。引擎盖，我们可以重新评估是否适当时机将表支持带回（drumroll）表！