🚀 在 VS Code 中！

介绍 Markdown 语言服务器

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

当我 2016 年加入 Visual Studio Code 时，Markdown 支持是我负责的第一个功能。哇，真的已经六年了吗？但这非常适合我。我使用 Markdown 的时间已经足够长了，以至于我经常发现自己满怀希望地在 Twitter、Outlook 以及几乎所有光标落入的文本框中输入反引号和星号。多年来，不断发展 VS Code 的内置 Markdown 支持，并看到我们的 Markdown 扩展如何直接或间接地塑造了 Webview 和笔记本等核心功能，这让我感到非常有成就感。

这就是为什么我很高兴分享一个我过去半年一直在默默努力的项目，以及一个我认为代表 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 支持的有限时间内成为可能。例如，我没有直接跳到构建重命名支持，而是首先获得了一个可靠的查找所有引用版本（因为如果您想重命名符号，您首先需要知道所有引用它的位置）。渐进式工作并在彼此之上构建每个功能也帮助我在实现新功能时测试旧功能。例如，在链接上实现重命名帮助我捕获了大量链接检测错误。（这种方法的唯一缺点是意识到您已经将您“如此优雅”的塔楼建立在一些非常复杂的正则表达式之上）。

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

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

我知道这些新工具将使 Markdown 的工作更快、更安全。但是，当我回顾这个编程语言通用的功能列表时，一个想法一直困扰着我。几个月前我把它当作荒谬的想法抛弃了，但现在，当我再次思考它时，我意识到也许是时候推出 Markdown 语言服务器了。

您正在被服务吗？

到 2022 年春末，VS Code 的所有 Markdown 工具仍然在普通扩展 API上运行。虽然我想探索将所有这些工具转移到适当的语言服务器上，但进行更改将产生实际的工程成本。我需要确保这是值得的。

我为此来回考虑了一个多月。即使现有代码状态良好，也存在很多未知数。如果我进行到一半才意识到它行不通怎么办？我以前甚至没有认真研究过语言服务器。

在讨论所有这些时，我让自己忙于重构 Markdown 扩展源代码，就好像它要被移动到语言服务器一样。我试图隔离对 VS Code 扩展 API 的依赖，我切换了更多逻辑以使用服务注入，并且我确保测试不依赖于文件系统。这样，即使我从未进行语言服务器的尝试，至少我也在清理代码库。

一些考虑最终让我相信 Markdown 语言服务器是正确的下一步。首先是一个相当平凡的考虑：我发现有效地为 Markdown 文件实现链接诊断非常具有挑战性。在像 vscode-docs 这样的大型 Markdown 工作区上，我不断意外地阻止扩展主机几百毫秒。不好。另一方面，语言服务器作为自己的进程运行。不仅如此，语言服务器现在还为诊断提供了一种新的拉取模型，我很兴奋能尝试一下。

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

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

如果没有关于如何实际构建语言服务器的计划，所有这些宏伟的思考都是无关紧要的。即使在我进行了所有重构之后，将代码移动到语言服务器仍然需要大量工作！这似乎令人难以承受，直到我意识到我不必一次完成所有工作。我可以逐步构建服务器，一次从 VS Code Markdown 扩展移动一个功能到新的 Markdown 语言服务器。如果我做得对，我可以签入每个小的增量迁移，以便用户在构建新的语言服务器时对其进行测试。理想情况下，用户永远不会注意到功能何时从扩展移动到语言服务器。

也许这很明显，但我已经成为这种类型的大型代码更改的增量方法的坚定拥护者。没有数十万 LOC 的 PR 或持续数月（或数年！）的大型功能分支。而是对 main 进行大量小的、安全更改。如果一切按计划进行，那么结束所有这些工作的提交应该是反高潮的。这就是我们逐步在整个 VS Code 代码库中使用严格的 null 检查所采用的方法，这就是我认为我可以快速且尽可能少地将 VS Code 的所有 Markdown 工具转移到新的语言服务器的方式。

剧透警告：它奏效了！我一次移动一个语言功能。我在实践中学习，并在明确需要时进行重构。诊断是最后一个要移动的功能，因为我不仅将它们移动到语言服务器，而且我还重写了它们以使用语言服务器的新拉取诊断模型。整个努力的最后一次提交主要删除了 Markdown 扩展中现在未使用的代码。因此，今天，如果您使用的是 VS Code 1.70+，几乎所有 Markdown 语言功能都使用新的语言服务器。

共同构建更好的 Markdown 工具

在许多方面，过去六个月 VS Code Markdown 工具的进步超过了我在这个领域工作的过去六年。今天，我们正在发布许多新工具，其中一些工具以前从未在 Markdown 中提供过。这些功能中的许多功能使最普通的 Markdown 阅读者和编写者受益，而另一些功能只有高级用户才会欣赏。然而，尽管取得了所有这些进步，但我知道我们才刚刚开始探索 Markdown 工具的可能性。

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

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

编码愉快！

Matt Bierner，@MattBierner