恭喜你已经掌握了多种Mermaid图表的“配方”！现在，我们进入一个非常实用的章节。学会写配方是一回事，但如何把这些配方应用到你的日常笔记、技术文档、团队协作和自动化流程中，是让这项技能真正发光发热的关键。

这一章，我们将学习如何将你编写的Mermaid图表代码，无缝地集成到各种主流的工具和平台中。

第四部分：集成与实战

第10章：Mermaid 生态系统与集成

10.1 在 Markdown 文件中标准用法

核心比喻：通用的“配方卡”格式

Markdown是一种非常流行的、用于编写文档的简单标记语言（比如你之前在GitHub上写的README.md文件）。它有一种标准的方式来嵌入代码块，而Mermaid图表正是利用了这一特性。

一步一步在Markdown中插入图表：

1. 在你的Linux终端里，创建一个Markdown文件。

   Bash

   nano my_report.md
   

2. 输入一些Markdown文本，然后像下面这样插入一个Mermaid代码块。

   Markdown

   # 我的项目报告
   
   这是一个关于项目流程的说明。
   
   ```mermaid
   graph TD
       A[需求分析] --> B[设计开发]
       B --> C[测试上线]
   

   以上就是我们的核心开发流程。

   **讲解**：
   * **` ``` `**：三个反引号（通常在键盘左上角，和`~`同一个键）用来开始和结束一个代码块。
   * **`mermaid`**：紧跟在开头的三个反引号后面，这个“语言标识符”是关键！它告诉任何支持Mermaid的渲染器：“嘿，这里面的代码不是普通文本，请把它渲染成一张Mermaid图表！”
   
   

保存这个.md文件。它现在就是一张包含了“图表配方”的卡片。要看到最终的图表效果，你需要一个能读懂这张卡片的“阅读器”，我们接下来就会讲到。

---

10.2 GitHub/GitLab 对 Mermaid 的原生支持

核心比喻：自带“魔法打印机”的图书馆

像GitHub和GitLab这样全球领先的代码托管平台（云端图书馆），已经内置了对Mermaid的支持。这意味着，当它们发现你的文档里有一张我们上面制作的“配方卡”时，它们会自动把它“打印”成漂亮的图表。

10.2.1 如何在 README 和 Issue 中使用

你几乎不需要做任何额外的事情，只需要按照10.1的标准格式把代码放进去就行。

一步一步在GitHub上展示你的图表：

1. 登录你的GitHub账号。找到你之前创建的 my_first_repo 或者新建一个仓库。

2. 编辑README.md文件。点击文件名，然后点击右上角的铅笔图标进入编辑模式。

3. 粘贴Mermaid代码。将10.1中我们创建的完整Markdown代码块粘贴到README.md的末尾。

   Markdown

   ```mermaid
   graph TD
       A[需求分析] --> B[设计开发]
       B --> C[测试上线]
   

4. 预览和保存。

   • 点击编辑框上方的“Preview”标签页。你会惊喜地发现，你的代码已经被自动渲染成了一张流程图！

   • 确认无误后，滚动到页面底部，点击“Commit changes”按钮保存。

现在，你的仓库首页就已经成功地展示了一张由文本代码生成的动态图表了！在Issue、Pull Request或Wiki中，使用方法完全一样。

---

10.3 在 VS Code 中高效编写 Mermaid

核心比喻：一个专业的“集成厨房”

虽然mermaid.live很好用，但在我们日常使用的代码编辑器（如VS Code）中直接编写和预览，效率会更高。VS Code就像一个专业的集成厨房，我们可以安装各种插件（厨具）来增强它的功能。

10.3.1 安装预览插件 (Markdown Preview Mermaid Support)

1. 打开你的VS Code。

2. 点击左侧边栏的扩展图标（四个方块的形状）。

3. 在搜索框中输入 Markdown Preview Mermaid Support。

4. 找到该插件，点击“Install”按钮。

10.3.2 实时预览与调试

1. 在VS Code中，打开我们之前创建的my_report.md文件。

2. 按下快捷键 Ctrl+Shift+V (或者点击编辑器右上角的预览图标)，打开Markdown的侧边预览窗口。

3. 体验实时预览！现在，当你在左侧的Markdown文件中修改Mermaid代码时（比如增加一个节点、改变一个箭头），右侧的图表会立即自动更新。这对于编写和调试复杂的图表非常有帮助。

10.3.3 导出为 SVG/PNG/PDF

有时候你需要一张静态的图片（比如插入到PPT或Word中）。我们可以借助另一个插件来完成。

1. 在VS Code的扩展商店中，搜索并安装一个流行的Markdown导出插件，比如 Markdown PDF。

2. 安装后，回到你的my_report.md文件。

3. 在编辑器中右键点击，在弹出的菜单里找到类似“Markdown PDF: Export (png)”或“(svg)”的选项。

4. 点击后，插件就会把你的文档（包括渲染好的Mermaid图表）导出为一张独立的图片文件，保存在当前文件夹中。

---

10.4 在笔记软件中无缝集成

很多现代笔记软件也内置了对Mermaid的支持，让你可以方便地在笔记中插入流程图、思维导图等。

10.4.1 Notion 中的 Code Block

1. 在Notion页面中，输入 /code 并回车，创建一个代码块。

2. 在代码块左上角的语言选择下拉菜单中，找到并选择 Mermaid。

3. 将你的Mermaid代码粘贴进去，Notion会自动将其渲染成图表。

10.4.2 Obsidian 中的 Mermaid 插件

Obsidian天生就是基于Markdown的，所以它对Mermaid的支持非常好。在绝大多数情况下，你只需要像10.1节那样，使用标准的 ```mermaid 代码块语法，Obsidian就会在你切换到阅读视图时自动渲染图表。

10.4.3 Joplin 中的 Mermaid 支持

Joplin同样内置了Mermaid支持。使用方法和标准Markdown完全一样，无需任何额外配置。

---

10.5 使用 Mermaid 命令行工具 (CLI)

核心比喻：一台自动化的“印刷机”

如果你需要批量地、自动化地将大量的Mermaid代码文件转换成图片，手动一个个导出太慢了。这时，我们可以使用命令行工具（CLI），它就像一台可以接收指令自动工作的印刷机。

前提：安装Node.js和npm 这个命令行工具是基于Node.js开发的，所以你需要先安装npm（Node包管理器）。

Bash

sudo apt update
sudo apt install nodejs npm

10.5.1 安装 (@mermaid-js/mermaid-cli)

1. 使用npm来全局安装Mermaid CLI。

   Bash

   sudo npm install -g @mermaid-js/mermaid-cli
   

   -g表示全局安装，这样你就可以在任何目录下使用mmdc命令了。

10.5.2 将 .mmd 文件转换为静态图表 (SVG, PNG)

1. 首先，创建一个专门存放Mermaid代码的文件，通常以.mmd为后缀。

   Bash

   nano my_diagram.mmd
   

   在里面粘贴你的Mermaid代码（比如那个流程图），然后保存。

2. 执行转换命令。

   Bash

   # 将 my_diagram.mmd 转换为 my_diagram.png 图片
   mmdc -i my_diagram.mmd -o my_diagram.png
   
   # 也可以转换为 SVG 矢量图
   mmdc -i my_diagram.mmd -o my_diagram.svg
   

   讲解：

   • mmdc：是Mermaid CLI的主命令。

   • -i：指定输入 (input) 文件。

   • -o：指定输出 (output) 文件。

3. 用ls命令查看，你会发现当前目录下已经生成了my_diagram.png和my_diagram.svg文件。

10.5.3 指定配置文件与主题

你也可以通过命令行来应用我们之前学过的主题。

1. 创建一个JSON格式的配置文件。

   Bash

   nano config.json
   

   输入以下内容来指定使用forest主题：

   JSON

   {
     "theme": "forest"
   }
   

2. 在转换时，使用-c参数来指定这个配置文件。

   Bash

   mmdc -i my_diagram.mmd -o my_diagram_forest.png -c config.json
   

   现在，新生成的my_diagram_forest.png就会是漂亮的森林主题了！