现已推出！了解 11 月的新功能和修复。

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 语言服务器。如果我做得正确，我可以检查每个小的增量迁移，以便用户在构建新语言服务器时对其进行测试。理想情况下，用户永远不会注意到功能何时从扩展移动到语言服务器。

也许这很明显，但我已经非常相信这种对大型代码更改的增量方法。不要有数十万行的 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 工具未来的邀请。如果您有兴趣参与贡献，请查看新项目，看看您可以使用它们创建什么。您可以提交错误报告和功能请求，甚至可以提交 PR！还有很多我甚至没有梦想过的智能 Markdown 语言功能。让我们一起构建它们！

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

祝您编码愉快！

Matt Bierner, @MattBierner