使用Mermaid在hugo的Markdown中绘制UML

辛琪

2021-08-19 2021-08-19 约 1012 字预计阅读 3 分钟次阅读

使用Mermaid在hugo的Markdown中绘制UML

简介 ¶

Mermaid是一个提供绘图功能的JavaScript项目。它目前（8.6.4）支持：

流程图——Flowchat
顺序图——Sequence Diagram
类图——Class Diagram
状态图——State Diagram
甘特图——Gantt
饼图——Pie
实体关系图——Entity Relationship Diagram
用户行程图——User Journey Diagram

使用 ¶

在Markdown中，使用Mermaid十分简单。

1
2
3
4
5
6
7


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

写出以上代码块，就可以在网页渲染时，自动变成以下的svg图。

1
2
3
4
5


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

本文不对如何用它表达思想，做过多描述，详见官网文档。此外，还可在其在线编辑器直接试用：mermaid-live-editor

以下介绍如何配置使用。

配置 ¶

在GitLab等平台中，内置了Mermaid，只是版本不是最新。想要使用，直接写就好。

在自己的hugo网站中，则需要在head.html这类的模板中，配置一番。确保在最后的网页中，在恰当的位置包含以下要素。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


<head>
    ...
    <script async src="https://cdn.staticfile.org/mermaid/8.6.4/mermaid.min.js"></script>
</head>
<body>
    ...
<script>
    // Replace mermaid pre.code to div
    Array.from(document.getElementsByClassName('language-mermaid')).forEach(el => {
        el.parentElement.outerHTML = `<div class="mermaid">${el.innerText}</div>`
    })
</script>
<style>
/* Set svg to center */
.mermaid svg {
    display: block;
    margin: auto;
}
</style>
</body>

其中，<head>部分是引入mermaid.js。这里使用的是staticfile.org作为CDN，可按需替换。

在<body>的最后，需要加上<script>这段，用处是替换mermaid代码块为<div>，确保mermaid.js开始工作。如果没有这段<script>，把````mermaid写成

`也是能用的，但不够优雅。

最后的<style>则是让svg居中显示。

另一种配置 ¶

以下是本站一次更新后的配置。除了CDN使用jsdelivr、版本更新为8.8.2以外，主要改动是在Hugo模板中添加了if。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


{{ if .Params.mermaid }}
<script
  src="https://cdn.jsdelivr.net/npm/mermaid@8.8.2/dist/mermaid.min.js"
  integrity="sha256-KqisLh8jVMBRjpNkOhH5W9VWs+F6x6vQksLqxs7+x9A="
  crossorigin="anonymous"
></script>
<script>
  // Replace mermaid pre.code to div
  Array.from(document.getElementsByClassName("language-mermaid")).forEach(
    (el) => {
      el.parentElement.outerHTML = `<div class="mermaid">${el.innerText}</div>`;
    }
  );
</script>
<style>
  /* Set svg to center */
  .mermaid svg {
    display: block;
    margin: auto;
  }
</style>
{{ end }}

额外加上了.Params.mermaid的检查，避免所有页面都需要加载它。在需要使用的Hugo页面，可以在Front Matter中添加一个配置，显式指定使用Mermaid。以下为TOML形式的示例：

1
2
3
4


+++
...
mermaid = true
+++

结语 ¶

用好Mermaid，可以让Markdown的表现力增色不少。以后，本站也会更多地使用它来做更好的表达。

目录

使用Mermaid在hugo的Markdown中绘制UML

使用Mermaid在hugo的Markdown中绘制UML

简介 ¶

使用 ¶

配置 ¶

另一种配置 ¶

结语 ¶