博客中使用 Mermaid

在 Jekyll GitHub Pages 博客中使用 Mermaid，最可靠的方法是通过 HTML 直接引入 Mermaid 的 JavaScript 库。这通常比安装插件更简单，也更容易排查问题。

具体的操作步骤如下：

1. 创建引入文件
在博客根目录下，新建 _includes/mermaid.html 文件。

2. 添加初始化代码
将以下代码粘贴进去。这会从 CDN 加载 Mermaid 库，并配置它扫描并渲染页面中 class="mermaid" 的代码块：

<!-- _includes/mermaid.html -->
<script>
  // 等待页面加载完成后初始化 Mermaid
  document.addEventListener("DOMContentLoaded", function() {
    // 从CDN加载Mermaid库
    var script = document.createElement("script");
    script.src = "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js";
    script.onload = function() {
      // 库加载完成后，初始化并配置主题
      mermaid.initialize({
        theme: "default", // 或者 "dark", "forest" 等
        // 更多配置选项可参考Mermaid官方文档
      });
      mermaid.run({
        nodes: document.querySelectorAll(".mermaid"),
      });
    };
    document.head.appendChild(script);
  });
</script>

3. 在主题中引用
打开 _layouts/default.html（或你的主题主布局文件），在 </body> 标签之前添加一行代码，引入刚才创建的文件：

<!-- _layouts/default.html -->
  ...
  {% include mermaid.html %}
</body>
</html>

4. 书写图表
现在，你可以在任何 Markdown 或 HTML 文件中，用 ```mermaid 代码块来画图了：

```mermaid
flowchart TD
    A[开始] --> B{判断条件}
    B -->|是| C[执行操作]
    B -->|否| D[结束]
```

---

⚠️ 特别提醒：Liquid 与 Mermaid 的冲突

如果你的 Mermaid 代码中包含花括号 { 或百分号 %，Jekyll 的 Liquid 模板引擎可能会误解析并报错。

解决方法：用 {% raw %} 和 {% endraw %} 标签将 Mermaid 代码块包裹起来，告诉 Jekyll“这部分代码不要处理”。

{% raw %}
```mermaid
graph TD
    A[开始] --> B{条件}
```
{% endraw %}

注意：如果使用此方法，必须将上面的 mermaid.initialize 配置中的 theme 与你的博客主题匹配（如 dark），否则图表可能看不清。

💎 其他方案与建议

• 使用支持Mermaid的主题：一些主题（如 jekyll-rtd-theme 或 Just-the-Docs）已内置支持，可直接使用。
• 排查故障：图表不显示时，打开浏览器“开发者工具”的“控制台 (Console)”，查看有无报错。
• 本地预览：部署前，务必在本地 bundle exec jekyll serve 预览，确保一切正常。

总的来说，通过 _includes 文件引入 JS 库是兼容性最好、最灵活的方式。如果遇到问题，别忘了检查 raw 标签的使用和浏览器控制台的报错信息。