在你的 Markdown 文件中使用 Mermaid 插入图表

一张图片胜过千言万语，但直到现在，在 GitHub 的 Markdown 文件中包含图片和图表的唯一方法是嵌入一张图片。我们最近增加了对嵌入 SVG 的支持，但有时你可能希望将图表与文档保持同步，并像使用 ASCII 艺术那样简单地创建一些东西，但要漂亮得多。

引入 Mermaid 🧜♀️🧜♂️

Mermaid 是一个基于 JavaScript 的图表和制图工具，它使用类似 Markdown 的文本定义，并在浏览器中动态生成图表。该工具由 Knut Sveidqvist 维护，支持多种常见的软件项目图表类型，包括流程图、UML、Git 图、用户旅程图，甚至包括令人头痛的甘特图。

通过与 Knut 以及 CommonMark 的更广泛社区合作，我们推出了一个更新，允许你使用 Mermaid 语法内嵌创建图表，例如：

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

上面的原始代码块在渲染后的 Markdown 中将显示为这个图表：

工作原理

当我们遇到标记为 mermaid 的代码块时，我们会生成一个 iframe，将原始的 Mermaid 语法传递给 Mermaid.js，从而在你的本地浏览器中将代码转换为图表。

我们通过两步流程实现这一点——GitHub 的 HTML 管道和 Viewscreen，这是我们内部的文件渲染服务。

首先，我们在 HTML 管道中添加了一个过滤器，用于查找带有 mermaid 语言标识的原始 pre 标签，并将其替换为一个渐进式的模板。这样一来，当客户端在非 JavaScript 环境（如 API 请求）中请求包含 Mermaid 的内容时，将看到原始的 Markdown 代码。

接下来，假设内容是在启用 JavaScript 的环境中查看的，我们会向页面中注入一个 iframe，并将 src 属性指向 Viewscreen 服务。这有几个优势：

• 将库的加载卸载到外部服务，减少我们需要通过 Rails 提供的 JavaScript 负载大小。
• 异步渲染图表，有助于减少在发送编译好的 ERB 视图到客户端之前，渲染多个图表的开销。
• 用户提供的内容被隔离在 iframe 中，降低了其在加载图表的 GitHub 页面上可能带来的安全隐患。

Mermaid 管道

以下是你带有 Mermaid 语法的 Markdown 变成完全渲染的 Mermaid 图表的路径的可视化表示。（此处是该图表的 Mermaid 代码。）

最终结果是快速、易于编辑、基于矢量的图表，正好嵌入到你需要的文档中。

Mermaid 在开发者中越来越受欢迎，并且由维护者 Knut Sveidqvist 领导的社区有着丰富的贡献者。我们非常感谢 Knut 对将此功能带给所有 GitHub 用户的支持。如果你想了解更多关于 Mermaid 语法的信息，可以访问 Mermaid 网站 或查看 Knut 的第一本官方 Mermaid 书籍。