在 VS Code 中尝试！

介绍 Markdown 语言服务器

2022 年 8 月 16 日，作者 Matt Bierner，@MattBierner

Markdown 支持是我在 2016 年加入 Visual Studio Code 时负责的第一个功能。哇，真的已经六年了吗？不过，这是一个很好的契合。我使用 Markdown 的时间足够长，以至于我经常发现自己希望在 Twitter、Outlook 以及我光标停留的几乎所有文本框中输入反引号和星号。多年来，能够发展 VS Code 内置的 Markdown 支持并看到我们的 Markdown 扩展如何直接或间接地塑造了像 webviews 和 notebooks 这样的核心功能，这令人无比欣慰。

这就是为什么我很高兴分享一个我过去半年一直在默默推进的项目，一个我认为代表 VS Code Markdown 工具下一个阶段的项目：Markdown 语言服务器。有了这个语言服务器，我们将 VS Code 大多数内置的 Markdown 语言工具——从文档大纲、智能折叠到路径补全——提供给其他编辑器和工具。我们的目标是利用通常与编程语言相关的智能来推动 Markdown 工具的发展。

Markdown 语言服务器的开发工作分为两个新的（且名称相似！）开源库

虽然这些库仍处于早期阶段，但它们已被 VS Code 1.70+ 版本使用（希望你甚至从未注意到 :-））。我们甚至看到了这种切换带来的一些好处，例如将 Markdown 工具移至单独的进程，这样就不会阻塞其他扩展。

但在我讲得太深入之前，也许你想知道：为什么需要 Markdown 语言服务器？坦白说，我自己花了这六年时间才认识到这一点。这也反映了我从最初只把 Markdown 看作是加入了一些星号、方括号和井号来活跃气氛的纯文本，转变为理解 Markdown 是一种标记语言，并且可以从我们为 TypeScript 或 Python 等编程语言提供的许多工具中受益。

深入了解 Markdown 工具

在我发现 VS Code 之前，我主要使用简单的文本编辑器进行编码。这意味着我必须记住符号名称，并在每次想要使用它们时手动输入。如果我想重命名一个变量，我会进行文本查找/替换，并希望我的单元测试能够捕获那些名称输入错误或被破坏的不可避免的情况。这是一种缓慢且不可靠的工作方式，但我很满足，因为我不知道还有更好的方法。直到我终于接触到更智能的工具后，才真正理解我的工作流程有多原始。

最近，我在 Markdown 上也有了同样的体会。多年来，我一直满足于使用 VS Code 相对简单的 Markdown 编辑器。我对语法高亮和内置的 Markdown 预览很满意。文档大纲和可点击的编辑器链接只是额外的好处。我习惯了手动写出链接。我开始接受，如果我改变了某个标题名称，我需要进行文本搜索来更新所有指向该标题的链接。而且因为我将 Markdown 看作仅仅是美化过的纯文本，我甚至无法想象还有更好的方法。

但有一天，在我感觉第一百次输错图片路径后，我终于醒悟了：这太没意思了！我为什么要浪费生命手动输入和验证这些链接？这不就是工具存在的意义吗！我知道我不想要任何工具，我想要一个能帮助我以文本形式阅读和编写 Markdown，而不是将 Markdown 源代码隐藏在某些所见即所得（WYSIWYG）式的 UI 魔法背后的工具。这非常符合 VS Code 的精神以及我们对编程语言支持的思考方式。为什么我们为传统编程语言提供的许多相同智能不能也应用于 Markdown 呢？第二天我就开始了链接补全功能的工作。

链接补全是帮助你编写指向当前文件内的标题或工作区中其他文件链接的建议功能。我甚至增加了对其他 Markdown 文件中标题链接的补全支持。太棒了！这是一个小小的增加，但对我的生产力产生了巨大的影响。很快我就无法想象没有它该怎么工作了。

沉浸在 Markdown 补全成功的喜悦中，我开始陶醉地想象接下来还能为 Markdown 带来哪些其他语言智能。我设想着自己自信地在标题上按下 F2 键来安全地重命名它们。我做着白日梦，想象着红色的波浪线穿过模糊的文本海洋，帮助识别无效链接。这一切看起来如此显而易见！为什么我几年前没想过呢？我开始将 Markdown 理解为结构化文本，而不仅仅是纯文本，而更好的 Markdown 工具的可能性似乎是无限的。

Markdown 语言特性

我不会用每个新功能背后的故事或其实现细节来让你感到厌烦。只需说，我采取了增量的方法，这使得我能够在有限的时间内投入到 VS Code 的 Markdown 支持工作中，并完成了所有这些努力。例如，我没有直接着手构建重命名支持，而是首先实现了可靠的查找所有引用功能（因为如果你想重命名一个符号，你首先需要知道它在所有被引用的地方）。增量工作并将每个功能建立在其他功能之上也帮助我在实现新功能时测试旧功能。例如，在链接上实现重命名帮助我发现了大量关于链接检测的 bug。（这种方法的唯一缺点是，你会意识到你那“如此优雅”的高塔是建立在几个非常复杂的正则表达式之上的）。

晚春时分，当用于报告无效文件/图片链接的实验性支持推出后，我退后一步审视了我的工作。现在 Markdown 语言功能集包括

  • 文档大纲
  • 工作区符号
  • 文档链接
  • 智能折叠
  • 智能选择
  • 补全
  • 重命名
  • 查找所有引用
  • 跳转到定义
  • 断开链接的诊断
  • 文件移动/重命名时更新链接

我知道这些新工具将使使用 Markdown 更快、更安全。但是当我回顾这些编程语言共有的功能列表时，一个想法一直在困扰我。几个月前我将其斥为荒谬，但现在，当我再次仔细思考时，我意识到可能是时候推出一个 Markdown 语言服务器了。

是否获得服务器支持？

到 2022 年晚春，VS Code 的所有 Markdown 工具仍然运行在正常的扩展 API上。虽然我想探索将所有这些工具迁移到一个合适的语言服务器上，但进行这种更改会带来实际的工程成本。我需要确保这样做是值得的。

我为此反复思考了一个多月。尽管现有代码状况良好，但仍有许多未知数。如果做到一半才发现它行不通怎么办？我以前甚至从未认真研究过语言服务器。

在我辩论这一切时，我一直忙于重构 Markdown 扩展源代码，就好像它将被移到语言服务器一样。我试图隔离对 VS Code 扩展 API 的依赖，我将更多逻辑切换到使用服务注入，并确保测试不依赖于文件系统。这样即使我从未真正投入语言服务器的工作，至少我也清理了代码库。

最终，几个考虑因素说服了我，Markdown 语言服务器是正确的下一步。首先是一个相当平凡的原因：我发现为 Markdown 文件高效实现链接诊断非常具有挑战性。在一个大型 Markdown 工作区，例如vscode-docs，我总是意外地阻塞扩展宿主几百毫秒。这不好。另一方面，语言服务器作为自己的进程运行。不仅如此，语言服务器现在还有了一种新的诊断拉取模型，我很想尝试一下。

然后还有更崇高的原因。例如，Markdown 语言服务器对其他编辑器和工具也会很有用。这包括 VS Code 团队发布的另一个编辑器：Monaco！更不用说像 Markdown CLI 工具的可能性了。如果我没有时间自己构建这样的工具，也许其他人可以使用语言服务器作为起点。我为 VS Code 的 Markdown 工具投入了大量工作，如果所有这些工作也能使其他人受益，那就太好了。

通过提供一个新的语言服务器，我也许能够启动围绕改进 Markdown 工具的共同努力。VS Code 既是开源软件的多产生产者，也是用户，我看到了这类项目提供的明显好处。一个开源的 Markdown 语言服务器将帮助其他编辑器，反过来也会吸引贡献，最终帮助 VS Code！与其让每个编辑器/工具重复努力实现自己的 Markdown 支持，语言服务器可以将开发者聚集在一起，为一个更大的项目工作，从而使每个人受益。

所有这些宏伟的思考如果缺乏如何实际构建语言服务器的计划，都是无关紧要的。即使在我进行所有重构之后，将代码迁移到语言服务器仍然需要大量工作！这似乎让人望而生畏，直到我意识到我不需要一次性完成所有事情。我可以增量地构建服务器，一次将 VS Code Markdown 扩展中的一个功能迁移到新的 Markdown 语言服务器。如果我做得对，我可以提交每个小小的增量迁移，这样用户就可以在构建过程中测试新的语言服务器。理想情况下，当一个功能从扩展迁移到语言服务器时，用户永远不会注意到。

也许这很明显，但我已经成为了这种对大型代码更改采用增量方法的坚定信徒。没有几十万行的 PR 或持续数月（甚至数年！）的大型功能分支。相反，对 main 进行一系列小而安全更改。如果一切按计划进行，完成所有这项工作的提交应该是平淡无奇的。这就是我们逐步在整个 VS Code 代码库中使用严格空检查的方法，这也是我觉得可以将 VS Code 的所有 Markdown 工具快速、尽可能顺利地迁移到新的语言服务器的方法。

剧透警告：成功了！我一次只迁移了一个语言功能。我在过程中不断学习，并在需要时进行重构。诊断功能是最后一个迁移的，因为我不仅将它们迁移到语言服务器，我还重写了它们，使其使用语言服务器新的诊断拉取模型。整个工作的最后一个提交主要是删除了 Markdown 扩展中现在未使用的代码。因此，今天，如果你使用 VS Code 1.70+ 版本，几乎所有 Markdown 语言功能都使用了新的语言服务器。

共同构建更好的 Markdown 工具

从许多方面来看，过去六个月在 VS Code 的 Markdown 工具方面取得的进展比我过去六年来在该领域工作的总和还要多。今天我们发布了许多新工具，其中一些以前在 Markdown 中是不可用的。这些功能中有许多对 Markdown 的普通读者和作者有益，而另一些则只有高级用户才能体会到其价值。然而，尽管取得了所有这些进展，我知道我们才刚刚开始探索 Markdown 工具的更多可能性。

真正让我对 Markdown 语言服务器感到兴奋的是，现在这个项目不仅仅局限于 VS Code。通过让我们的 Markdown 工具易于使用，我希望我们可以帮助推动 Markdown 工具向前发展，造福所有人。这些开源项目是邀请大家共同构建 Markdown 工具未来的邀请。如果你有兴趣贡献，请查看这些新项目，看看你可以用它们创造什么。你可以提交 bug 报告和功能请求，甚至可以提交 PR！还有许多我甚至从未梦想过的智能 Markdown 语言功能。让我们一起构建它们吧！

如果你有兴趣查看源代码或贡献，可以在 GitHub 和 npm 上找到 Markdown 语言服务和服务器

编程愉快！

Matt Bierner, @MattBierner