问题背景

以往我都是自己手绘图。近来因为各种原因，了解到大部分技术者越来越地使用 mermaid 来绘制各种流程图。有一个在线编辑和预览功能，我使用了下，确实非常简洁方便。实际使用时，VSCode中的 markdown 也支持 mermaid 的直接预览，相对会更方便一些。

我现在对 mermaid 还不太熟悉。如果你有相对复杂的业务图标的绘制需求，我可能还是建议先用 drawio。

不过，说实话，不管用什么工具，似乎都没有我在纸上手绘的流程图，有神韵。总觉得缺少了点什么。可能的原因是：手绘时，我可以集中注意力在要表达的逻辑本身；而借助工具时，可能不得不受到工具本身的各种桎梏。

所以说，初始版本，可能还是手绘比较好。先手绘，理清自己的思路，然后再借助工具，沉淀下来，同时便于共享与后期修改。

在网页中基于 mermaid 绘制流程图的原理

graph TD;
    A[页面 mermaid 代码]-->B[网页加载完成]-->C[ mermaid 库将代码绘制为SVG] --> D[将 SVG 图替换到 Dom 中的代码];

具体要修改的文件：

files_change

  • 完整路径: _includes/footer-script.html
  • 作用：新增文件，主要用于放一些自定义的JS的代码。
  • 代码：文件内的完整代码如下。

{%- if page.mermaid -%}
    <script src="https://code.jquery.com/jquery-3.7.1.min.js" integrity="sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo=" crossorigin="anonymous"></script>
    {%- include mermaid.html -%}
{%- endif -%}

footer.html

  • 完整路径: _includes/footer.html
  • 作用：初始版本，请从系统主题目录中查找。确认 minima 主题本地安装目录的命令如下:
bundle info --path minima
  • 代码：在主题初始代码的末尾添加上下述代码。

{%- include footer-script.html -%}

mermaid.html

  • 完整路径: _includes/mermaid.html
  • 作用：用于mermaid代码的动态渲染。本次的核心。
  • 代码：完整代码如下。 mermaid 不同版本，API可能有差异，请自行对应修改。
<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.0/mermaid.min.js"></script>
<script>
  $(document).ready(function () {
    // 可选主题，参考：https://mermaid.js.org/config/theming.html#available-themes
    mermaid.initialize({
        startOnLoad: false,
        theme: "default",
    });

    // 不同版本的 API 有差异，参考：https://github.com/mermaid-js/mermaid/blob/release/10.8.0/docs/config/usage.md
    mermaid.run({
        querySelector: '.language-mermaid',
    })
  });
</script>

github-syntax-highlighting.scss

// 使 mermaid 居中显示。ref: https://github.com/mermaid-js/mermaid/issues/150#issuecomment-689353672
code.language-mermaid { 
	display: flex !important; 
	justify-content: center;
}

博客本身的修改:

mermaid: true

考虑到性能，默认不支持 mermaid。需要支持的话，开头加上上述代码即可。

参考: