想要创建引人入胜、互动性强的文档？不妨试试这些出色的文档工具和示例

技术文档的名声不太好。技术文档和博客文章往往枯燥、线性、静态。它们读起来更像是一本说明书，而不是一篇叙述。

当我看到数据新闻如何影响新闻出版物的叙事水平，让文章充满丰富的可视化和互动性时，我不禁感到困惑。为什么开发者们没有制作出这样引人入胜、身临其境的文档呢？

我相信，让代码故事更具表现力、更具启发性，还有许多尚未实现的潜力。教程和技术博客可以做得更好。

精彩的技术故事是什么样的？

我读到的第一篇博客文章，以抽象的技术主题——系统设计——为题材，并呈现出丰富的视觉交互体验，是Bret Victor 的《Up and Down the Ladder of Abstraction》。对于这个主题来说，这篇文章很容易让人感到乏味。然而，Bret 却创作了一篇优美而引人入胜的探索文章，他称之为“视觉散文”。

布雷特以设计一个简单的汽车模拟控制系统为例，并在整篇文章中引用它，并在叙述中附带视觉效果和交互式小部件。

就连文章的主角部分，都有一辆可以控制的车，还能跳上梯子！这篇文章写于2011年，真是奇怪，即使是现在，你也很难看到这种水准的文章了！

如果您不是设计师或特定类型的前端开发人员，您可能会认为我无法创建这样的视觉效果！

这是一个合理的担忧！

我现在想再给你们展示几个例子，稍后我会向你们展示一些简单、常见的模式，这些模式可以从这些例子中推断出来，帮助每个人创建更好的技术文档。它不一定非得是一篇“视觉文章”，但我们可以从中汲取灵感。

如今，视觉文章最常见的来源是数据可视化（data viz）社区。像《The Pudding》这样的出版物涵盖了各种各样的主题。然而，这些主题并非 Web 开发。但为了创作视觉文章，作者必须了解 Web 开发，对吧？那么，为什么他们不以类似的方式解释 Web 开发主题呢？那不是很棒吗？

嗯，Amelia Wattenberger 是数据可视化学院的成员，她曾是The Pudding 的撰稿人，并在自己的博客上探讨过一些 Web 开发主题。以她关于CSS Cascade 的文章为例。她真的在文章中嵌入了一个卡通瀑布，并把它作为一个粘性部分！瀑布本身就是一条河流，当你滚动浏览文章时，会有一个皮划艇顺流而下。🚣

虽然在阅读时有皮划艇爱好者陪伴很酷，但一个简单的问答小部件也能带来很多价值。它旨在挑战读者，并测试他们的理解能力。它只有两个代码块和一个带有模糊前景的答案块，点击即可显示答案。

作为一名设计方面有挑战性的开发人员，您可以实现这一目标，对吗？

确实，像这样简单的点缀就能提升文章或技术文档的水平。孔子曾言：“言而无信，行而忘；言而无信，行而明；言而无信，行而明。”

以下是一些与 Web 开发相关的优秀交互式文章的示例：

• 重建 Babel：Nanda Syahrasyad 的 Tokenizer：最突出的部分是 Nanda 有一个自定义小部件来逐步完成标记化过程，并显示中期结果。
• 三次贝塞尔曲线：从数学到运动，作者：马克西姆·赫克尔：啊，数学方程式！如果说有什么话题需要交互式可视化示例，那就是这个了！
• 哪种混合模式？作者：Chris Nicholas：这是一本关于如何使用 CSS 混合模式的实用指南，其中包含大量交互式示例来展示不同混合模式的不同结果。

Delba Oliveira 也写过一系列鼓舞人心的互动文章。在她关于互动游乐场的文章中，她写道：

网络为主动学习提供了尚未充分利用的一个机会，那就是互动。创建互动内容既耗时又更具技术挑战性。但如果主动学习更有效，我认为值得一试。

这涵盖了一次性文章。那么技术文档 (docs) 呢？

Stripe是技术文档领域的先驱。他们的文档包含示例代码演示。Stripe 很聪明地将此视为一个机会。他们的核心受众是开发者。他们能够消除任何障碍，让开发者更容易理解他们的SDK和API，这将提升其产品的采用率。这应该会增加他们的收入。🤑

观看下面的视频，了解 Stripe 文档如何引导您完成一个大示例。

最后， Yoksel 的 flex cheatsheet是一个很好的例子，它展示了如何让技术文档更易于理解。她采用了CSS 弹性框布局模块 1 级W3C 规范，并将静态示例转换为交互式示例。

你喜欢这个版本吗？

还是原版的？

这怎么就不是常态了？😃

这件事还有点意思。目前，Eric Meyer 和 Estelle Weyl 正在完成一本老书《CSS：权威指南》的新版本。Estelle最近在JS Party 播客的一期节目中说，有人建议将这本书的副标题定为“我们阅读规范，所以您不必阅读”，但这个想法被否决了！

我们现在正在收尾。Eric Meyer 负责大部分内容，但我在帮忙，我想给它加个副标题：“我们读了规格书，所以你不用读。”

奥莱利对此予以了否决，但他们确实表示会将其放在封底。

虽然我理解这些规范主要是为浏览器厂商编写的，但我也读过一些，并且时不时地会参考它们。那么，为什么不把它们变成更通俗易懂的资源呢？

现在，我想探索新一波的开发文档工具，它们有可能创建更好的文档。

通过 Shiki 使用 VS Code 的主题和语言语法

语法高亮在技术博客和文档中随处可见。您可以通过高亮语法来帮助开发人员理解代码，就像他们最喜欢的文本编辑器一样。

但问题是，大多数语法高亮库并不像你常用的文本编辑器那样高亮代码。有些库在提取语义标记方面做得很粗糙。许多库缺乏对框架的支持。你可能需要自己寻找一个 CSS 文件，才能将你最喜欢的主题添加到浏览器中。

早在六月份，我就对语法高亮库做了一个简短的评测，看看它们对现代前端框架的支持程度如何。结果发现，它们都没能跟上时代！

这让我想到了以下疑问：

我想知道，目前支持部分代码编辑器功能的语言服务器协议 (LSP)是否提供了一种简单的方法来抽象出语义高亮部分。遗憾的是，不同的库都在做同样的事情，却没有完全覆盖所有基础功能。

换句话说，为什么不重复使用 VS Code 等文本编辑器中的内容呢？

我（主要）期待的结果已经被Shiki图书馆实现了！顺便说一句，这个想法我并不居功，只是很高兴有人（Pine）接受了它！

Shiki是一个基于 VS Code 语法高亮功能的语法高亮库。

这个决定的第一个重大回报是，您可以使用任何 VS Code 主题来语法突出显示您网站上的代码块。

只需更改此行即可在捆绑主题之间切换：

shiki.getHighlighter({
  theme: 'nord'
})

简单又方便！

Shiki 适合在构建时或服务器上使用。它的解压包大小为 8.42MB ，所以除非你想让用户感到不适，否则最好不要在浏览器中使用它！🤣

如果要在浏览器中使用库，像Prism这样的轻量级库更适合。

第二个好处是 Shiki 支持超过 100 种语言和框架。

此外，你更有可能高亮你最喜欢的前端框架，而无需自己摸索如何操作。这是因为 Shiki 使用TextMate 语法进行语言定义，许多流行的文本编辑器都支持该语法，包括 VS Code、Sublime Text 和 Atom。基本上，如果这些文本编辑器中某个框架或语言支持语法高亮，那么你可以直接获取其语法文件并将其加载到 Shiki 中，以高亮显示代码的语法。

我喜欢 Shiki 的另一个原因是，语义标记的颜色默认以内联样式添加。跳过样式表可以提高页面的渲染性能。

最后但并非最不重要的一点是，利用 VS Code 的功能意味着您可以获得高度准确的语法突出显示。

感谢Pine制作了这个。如果您用了这个，可以考虑赞助他。

其他功能怎么样？

Shiki 还处于早期阶段。当前版本是 v0.11.0。我希望它能带来更多功能。

其他语法高亮库提供的一些最常见的功能却缺失，例如：

1. 显示行号来引用您正在讨论的代码，
2. 突出显示行或单词以引起对代码特定部分的注意，
3. 能够添加自定义类和属性来设置样式并显示文件名等附加信息。

由于 HTML 标记结构良好，您可以使用一些 CSS 显示行号。

code {
  counter-reset: step;
  counter-increment: step 0;
}

code .line::before {
  content: counter(step);
  counter-increment: step;
  width: 1rem;
  margin-right: 1.5rem;
  display: inline-block;
  text-align: right;
  color: rgba(115,138,148,.4)
}

其余功能需要构建。您可以在 GitHub 问题中查看所请求的功能，以了解其进展情况。

有些人已经在独立构建其中一些功能。例如，Shiki 的一个分支Shiki-Twoslash（Twoslash）添加了诸如行高亮和 TypeScript 元数据注释等功能（随便说说吧！）。

让我们看一下 Twoslash 的 typescript 元数据注释，看看它如何提升浏览器中的代码块。

使用 Twoslash Shiki 将 TypeScript 编译器元数据嵌入代码块中

Shiki Twoslash（Twoslash）是 Shiki 代码渲染引擎的一次“礼貌但艰难的分叉”。非常贴心！💕

Twoslash 带来了两个主要新增功能。

首先，它带来了元数据。它可以将类型显示为悬停信息、准确的错误信息以及 TypeScript 编译器提供的其他 JavaScript 和 TypeScript 代码标注。

您的文本编辑器可以告诉您有关代码的任何信息，Twoslash 都可以将其包含在代码块中。

例如，这是在 Express 应用程序上工作时的预先输入对话框：

其次，Two Slash 让你能够创建相互关联的代码块。它有一个自定义指令，你可以引用之前的代码块。因此，你可以编写一个代码块并进行一些解释，然后编写另一个延续前一个代码块的代码块并进行更详细的解释。它与Jupyter Notebookinclude类似。

为了更深入地了解 Twoslash，请仔细阅读其主页上的示例。

它已经与流行的 JavaScript 工具（如eleventy、Gatsby和Docusaurus）集成。

Fatih Kalifa 撰写了一篇演练，介绍如何使用 Twoslash 在他的 Gatsby 网站上添加构建时类型注释和语法突出显示。

感谢Orta制作了这个。如果您用了这个，可以考虑赞助他。

使用 Code Hike 进行交互式代码演练

Code Hike是 MDX 的一款注释插件。它旨在提供更引人入胜的代码叙事方式。

目前，Code Hike 只能与 React 一起使用。😒 希望未来支持能够得到改善。

Code Hike 有几个简洁的功能我想向您展示一下。

Code Hike 有一个自定义<CH.Spotlight>组件，可让您将读者的注意力集中在代码块的不同部分。它可以使周围的代码变暗或以动画形式显示，并引入新的部分或文件。这让人想起了 Stripe 文档。

检查演示以并排查看源 MDX 文件和输出。

你创建一个<CH.Spotlight>组件，并在其中放置 Markdown 代码和一些自定义注释。创作体验非常愉快。

将此聚光灯功能与滚动触发事件相结合，即可获得滚动编码 (scrollycoding)。这是一种简洁优雅的方式，可以让您像激光一样专注地单步执行代码。查看演示，并排查看源 MDX 文件和输出。

您可以观看下面的视频来了解其实际运行情况。

Rodrigo Pombo 是 Code Hike 的创建者。他一直致力于开发工具，使代码和技术数据更易于理解。此前，他曾使用类似的技术，通过git-history 让你的 git 历史记录更易于浏览和理解。

如果您想了解更多 Code Hike 的功能，Rodrigo 做了一个与 Code Hike 相关的演讲，题为“别再写死鱼了” 。演讲的标题是Bret Victor 的演讲，所以我非常赞同！

感谢Rodrigo 的创作。如果您使用了这个项目，请考虑赞助。

UI模式

技术文档中出现了一些 UI 模式，我们可以将它们应用于任何包含技术内容的文档。让我们来探讨一下这些模式，希望它们能够得到更广泛的应用。

选项卡式视图显示不同语言和包管理器的片段

在标签视图中显示不同的文件听起来很常见，但它的使用并不像你想象的那么广泛。它通常用于文档中，显示不同包管理器的说明，或者显示同一示例在不同编程语言中的代码。

例如，使用eleventy (11ty) 静态网站生成器，您可以使用多种不同的模板语言来创建网页。文档中的说明使用选项卡式窗格中四种最常用的模板选项来演示概念，如下所示。

Astro框架在其文档中对此进行了更进一步的改进，通过在同一页面中协调选项卡式实例的选择。例如，在“集成”指南中，他们提供了有关如何为集成添加正确软件包的说明。他们提供了一个选项卡式视图，其中为每个最流行的软件包管理器（npm、pnpm 和 yarn）分别提供了一个选项卡。在第一个实例中选择“pnpm”，会将页面中所有选项卡式实例的活动选项卡切换为“pnpm”。

Stripe 在其文档中采用了略有不同的方法。他们有一个包含源文件的选项卡式预览窗格，并附带 3 个列表来选择平台、前端环境和后端语言。更改这些选择将会替换选项卡式预览窗格中的源文件。

HTML 中没有 tabbed view 元素，所以很遗憾，这可能会导致人们自行创建实现。Open UI 项目正在研究tabs 元素的提案。希望它能早日实现！🤞

文件树展示项目结构

通过文件树来解释项目结构是静态站点生成器和框架的常见需求。随着框架根据文件存放位置来执行路由和其他任务，这一点变得越来越重要。

展示文件树最常用的方法是使用纯文本代码块，并使用斜线和缩进来显示文件夹结构。有点像ASCII 艺术！

这是 Astro 文档中的一个示例：

突出显示文件夹和添加工具提示的功能将有助于演练。

下面是 Astro 文档的摘录，其中有一个讨论页面路由的示例，它们突出显示了文件树中的某些文件。

我还没有在任何地方看到过将其正式化为一项功能。

源和输出的集成视图

为了解释库或语言的语法，有一个集成的视图来并排显示源和输出会很有帮助。

我们在Shiki Twoslash 文档中看到了对其注释语法的解释。

在文章中，我们经常会看到一个完整的示例被嵌入到 Codepen 中，或者使用一些外部代码沙盒环境。输出（预览或结果）是源文件的渲染。这样做的问题在于，它会将用户带离文档的创作体验。

作为一种 UI 模式，你应该能够定义源和输出。从创作的角度来看，无论是预渲染还是像代码沙盒一样可编辑，都无关紧要。

选择性聚焦以逐步执行代码

将读者的注意力引向代码的不同部分，有助于读者循序渐进地理解代码。Rodrigo Pombo 将这种模式称为“代码聚光灯”。

最简单的形式是高亮代码块中的一行。在语法高亮库中，为 Markdown 代码块添加自定义注释来高亮行是很常见的做法。

例如，Twoslash 允许通过 codefence 注释中的列表来高亮显示单行代码或指定行范围。注释由一组花括号括起的数字组成，例如，{1, 3}将高亮显示第 1 行和第 3 行。范围由两个数字用连字符连接表示，例如，{3-5}指定要高亮显示第 3 行至第 5 行。请参阅下面的示例。

不同的库中，这种注释语法有所不同。

更复杂的形式是允许用户在代码块中更改焦点。你可以在 Stripe 文档中看到这种实现。

例如，在自定义支付流程页面上，您可以点击侧面板中的步骤跳转到代码的重点部分。

滚动讲述

Scrollytelling 使用滚动位置来控制向读者显示的内容。这对于代码演示非常有帮助。

再次，您可以访问Stripe 文档的自定义支付流程页面，并滚动浏览，以查看此模式的详细说明。滚动时，预览窗格会以动画形式将代码聚焦，从而将叙述与特定的代码段联系起来。

我见过的大多数人都在使用 MDX 和 React，比如Varun Vachhar和Code Hike。我希望看到一种更通用的方法，而Intersection Observer API是关键要素。

问答视图

再说一遍，这听起来很简单，但很少见。向读者提问可以更好地吸引读者。你可以设置一个窗格显示问题，另一个窗格显示答案，并以交互方式显示。

正如前面提到的，Amelia Wattenberger 在她的文章《CSS Cascade》中做到了这一点。

总结

创造优秀的交互式内容需要时间和精力。我希望通过本文中展示的示例、工具和 UI 模式，您能够明白，任何具备一定开发技能的人都可以实现这一点。

有迹象表明，大家渴望创作更具吸引力、包含技术内容的叙事，而且也出现了一些工具来促进这一进程。不过，现在感觉还处于早期阶段，我们还需要更多帮助！

分析 Stripe 在这方面的举措很有意思。他们创建了自己的基于 Markdown 的文档格式Markdoc，旨在满足面向用户的产品文档需求。关于创建 Markdoc 的原因，他们是这样解释的：

我们选择 Markdown 作为起点，是因为它易于阅读和理解，许多工程师和技术作家都已经熟悉它，并且得到了众多现有工具的广泛支持。然而，Markdown 本身并不适合编写像文档这样复杂、高度结构化的内容。

Markdoc 提供了一个可扩展的系统，用于定义可在 Markdown 内容中无缝使用的自定义标签。使用自定义标签语法，我们可以表达更精细的文档层次结构、插入交互式组件，并支持条件内容、内容包含和变量插值等功能。Markdoc 对 Markdown 语法的扩展旨在实现可组合性且侵入性极低，从而在提供关键功能的同时，又不损害文章的可读性。

它的核心是对流行的开源 Markdown 库markdown-it 的扩展。Markdown 解析器和预处理器的插件为此类创新提供了途径。

基于 Markdown 的格式日益增多，为文档集成交互式内容提供了可能性，即在 Markdown 中使用 Web 组件。MDX支持在 Markdown 中使用JSX，其主要目的是将 React 组件引入 Markdown。Mdsvex则为Markdown 带来了精简的组件。

乍一看可能不太一样，但 Markdoc 和 MDX 确实是两种不同的方法。Stripe 在“为什么不使用 MDX？”这个问题的答案中很好地总结了这一点。

MDX 是 Markdown 的一个变体，允许用户嵌入用 JavaScript 和 React 的 JSX 模板语法编写的内容。与 Markdoc 类似，MDX 可以将 React 组件合并到文档中。两者之间的关键区别在于，MDX 支持任意复杂的 JavaScript 逻辑（可以理解为：文档即代码），而 Markdoc 则严格区分代码和内容（可以理解为：文档即数据）。

Markdoc 使用完全声明式的方法进行组合和流程控制，而 MDX 则依赖于 JavaScript 和 React。这意味着 MDX 为用户提供了更强大的功能和灵活性，但代价是复杂性——内容很快就会变得像常规代码一样复杂，这可能会导致可维护性问题或更困难的创作环境。

在 Stripe 创建 Markdoc 的主要动机之一是创建一种针对写作而不是编程进行优化的格式，以便我们能够克服因我们遗留的文档平台中混合代码和内容而带来的挑战。

我不太理解他们提到的“文档即代码”和“文档即数据”之间的二分法，但我同意这样的观点：创作体验应该针对内容编写而非代码编写进行优化。我需要更详细地研究 Markdoc 和 MDX，才能理解这种区别的细微差别。

另外，我认为重要的是不要被工具所束缚。工具不应该决定信息。你不应该感觉自己把内容嵌入到代码中。此外，将类似代码的片段放入文档中不应该导致维护上的麻烦。

以正确的方式分离关注点并非易事。我们的目标是创造一种能够简化交互添加的创作体验。

我希望看到这个领域有更多的创新。

感谢阅读！