🍡 Mermaid — 超好用的文档图形工具！ [ 🍧 Peach ]

🍡 Mermaid — 超好用的文档图形工具！

2020-04-02#Mermaid #Markdown

一. Markdown

（略

二. Mermaid

1. 为什么用 Mermaid

在配合 Markdown 写笔记时，最让我头疼的就是如何以最省时省力的方式插入流程图。我做过很多尝试：如，手绘、使用Xmind导图软件、ProcessOn之类的在线绘图工具等。但它们都有最显著的缺点：最终以图像形式导入文档，因此修改和导出非常繁琐。

而 Mermaid 对我来说是一个说近乎完美的方案！

高效易用
- 它直接在 Markdown 中以代码段的形式创建和修改图表，并实时渲染为 Svg 视图，可以高效制作简易的流程图。并且随时修改、立即可见。
- 它和 Markdown 一样都是纯文本格式存储的语言，易于保存和分享。
Web友好
- 它不受制于特定编辑器，大部分支持 Markdown 的编辑器都支持 Mermaid。
- 它基于 Javascript，可集成嵌入前端框架，如 Vue、Hexo等。

2. Mermaid 用法

Mermaid 可绘制流程图、时序图、Git图、类图、饼图、甘特图等图表，详细可查阅官方文档。
下面以我常用的两个流程图模版作为示例（主要展示样式的两种使用方法）：

基础（使用基本样式）

  graph LR

T(("Title")):::p
T ==> A(["Pink"]):::p
T --> B(["Green"]):::g
T --> C(["Blue"]):::b
A -.-> a("light Pink"):::lp
B -.-> b("light Green"):::lg
C -.-> c("light Blue"):::lb
a -.- info["Info"]:::info

classDef p fill:#ddaebd
classDef b fill:#aab7d2
classDef g fill:#9ac5bb
classDef lp fill:#f4e4e9
classDef lb fill:#d9dfeb
classDef lg fill:#ddebe6
classDef info fill:#f6f6f7,color:#737379,stroke-dasharray: 3 3, stroke-width: 2px

 graph LR

 T(("Title")):::p
 T ==> A(["Pink"]):::p
 T --> B(["Green"]):::g
 T --> C(["Blue"]):::b
 A -.-> a("light Pink"):::lp
 B -.-> b("light Green"):::lg
 C -.-> c("light Blue"):::lb
 a -.- info["Info"]:::info

%% 样式：
 style T color:#fff
 classDef p fill:#ddaebd
 classDef b fill:#aab7d2
 classDef g fill:#9ac5bb
 classDef lp fill:#f4e4e9
 classDef lb fill:#d9dfeb
 classDef lg fill:#ddebe6
 classDef info fill:#f6f6f7,color:#737379,stroke-dasharray: 3 3, stroke-width: 2px

进阶（使用预加载样式）

  %%{
     init: {
   'themeVariables': {
     'fontFamily': 'Noto Serif SC',
     'mainBkg': '#f4e4e9',
     'edgeLabelBackground': '#ddebe6'
   }
 }
}%%
graph TD

T(("Title")):::pink
T --> A
A -.-> |"text2"| B
subgraph "subgraph"
A --> |"text3"|C:::lb
end

classDef pink fill:#ddaebd
style B fill:#d9dfeb, stroke:#657eae,stroke-width:3px,stroke-dasharray: 5 3

%%{
  init: {
    'themeVariables': {
      'fontFamily': 'Noto Serif SC',
      'mainBkg': '#f4e4e9',
      'edgeLabelBackground': '#ddebe6'
    }
  }
}%%
graph TD

T(("Title")):::pink
T --> A
A -.-> |"text2"| B
subgraph "subgraph"
A --> |"text3"|C:::lb
end

classDef pink fill:#ddaebd
style B fill:#d9dfeb, stroke:#657eae,stroke-width:3px,stroke-dasharray: 5 3

3. Hexo + Mermaid 插件

代码仓库: https://github.com/webappdevelp/hexo-filter-mermaid-diagrams

（1）安装插件

$ yarn add hexo-filter-mermaid-diagrams 
或 $ npm install hexo-filter-mermaid-diagrams

（2）编辑配置

安装完成后，编辑hexo配置文件：config.yml

# mermaid chart
mermaid: 
  enable: true  
  version: "7.1.2" 
  options:

（3）添加脚本

修改完配置文件后，编辑博客页面组件的footer部分。这是为了将 mermaid.js 以 script 形式插入到 html 尾部，使其能正常渲染。

footer文件如，footer.pug， after_footer.pug , after-footer.ejs 或 swig，该文件通常存放在主题目录下的layout目录中。

若博客使用pug模版引擎渲染，在 after_footer.pug文件中添加如下代码:

if theme.mermaid.enable == true
  script(type='text/javascript', id='maid-script' mermaidoptioins=theme.mermaid.options src='https://unpkg.com/mermaid@'+ theme.mermaid.version + '/dist/mermaid.min.js' + '?v=' + theme.version)
  script.
    if (window.mermaid) {
      var options = JSON.parse(document.getElementById('maid-script').getAttribute('mermaidoptioins'));
      mermaid.initialize(options);
    }

若使用ejs引擎渲染，则在after-footer.ejs文件中添加如下代码：

<% if (theme.mermaid.enable) { %>
  <script src='https://unpkg.com/mermaid@<%= theme.mermaid.version %>/dist/mermaid.min.js'></script>
  <script>
    if (window.mermaid) {
      mermaid.initialize({theme: 'neutral'});
    }
  </script>
<% } %>

swig模版引擎：

{% if theme.mermaid.enable %}
  <script src='https://unpkg.com/mermaid@{{ theme.mermaid.version }}/dist/mermaid.min.js'></script>
  <script>
    if (window.mermaid) {
      mermaid.initialize({{ JSON.stringify(theme.mermaid.options) }});
    }
  </script>
{% endif %}

（4）踩坑

以上为官方文档中的配置方法，而我在初次配置的过程中，还遇到以下问题可供参考：

html页面中，mermaid段落仅显示为代码块，开发者工具中该段落为普通源代码。

这是因为插件没有生效，应确保正确完成上面两个步骤（安装插件、打开配置）。

html页面中，mermaid段落显示为空白图片，开发者工具中查看该段落为svg文件，
控制台报错： Uncaught TypeError: Cannot read properties of null (reading’mermaid’)。

此时插件已经生效，而js代码文件引入有误，无法成功渲染。

继续查看html代码发现，文件底部的<sctipt>标签中，显示我引入mermaid的url为：
<script type="text/javascript" id="maid-script" src="https://unpkg.com/mermaid@10.0.2/dist/mermaid.min.js?v=undefined"></script>
这段代码是由官方提供的脚本、在footer文件中根据用户的配置组合成的：
script(type='text/javascript', id='maid-script' mermaidoptioins=theme.mermaid.options src='https://unpkg.com/mermaid@'+ theme.mermaid.version + '/dist/mermaid.min.js' + '?v=' + theme.version)
如果配置有误则会生成错误的url，看起来是version的问题，于是我将url改为直接引入jsdelivr上的资源，遂能正常渲染：
src='https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js')

🍧 Peach