Hugoにmemaidを組み込んでみた

mermaidとは

Web上でいろんな図が書けるJavaScriptのライブラリです。1つ前のポストに参加レポートを書いたGitLab Meetupで知りました。d3.jsをラップして特定の図を簡単に書けるようにした感じなようです。

GitHub - mermaid-js/mermaid: Generation of diagram and flowchart from text in a similar manner as markdown

Generation of diagram and flowchart from text in a similar manner as markdown - GitHub - mermaid-js/mermaid: Generation of diagram and flowchart from text in a similar manner as markdown

Hugoにmemaidを組み込んでみる

このブログでmermaidが使えるようにHugoのtheme組み込んでみました。

ほとんどこちらのQiitaの記事を参考にさせてもらいました。

Hugoにmermaidを組み込んでみた - Qiita

Hugoにmermaidを組み込んでみたの抜粋版です

What's mermaid ?

フローチャートやシーケンスダイヤグラムやガントチャートをサクサクと書くことのできるライブラリです

公式サイト：mermaid

設定メモ…

一時期メンテナンスが停止していたのでForkして自分でメンテナンスしているhugo-robust-themeに組み込んでみます。

marmaid.jsをダウンロード

https://unpkg.com/mermaid/dist/ からmermaid.min.jsをダウンロードしてthemeのstatic/js/mermaid.min8.0.jsとして保存しました。minでも1.1MBあるので結構巨大です。

ShortCodeを作成する

下記のように作成してlayouts/shortcodes/mermaid.htmlとして保存しました。mermaid.min.jsファイルが前述のとおり大きいため必要ない記事では読み込みたくないのでShortcode内で読み込むようにしました。

<script src="{{"js/mermaid.min8.0.js" | relURL}}" defer></script>
<div class="mermaid" align="{{ if .Get "align" }}{{ .Get "align" }}{{ else }}center{{ end }}">
    {{ safeHTML .Inner }}
</div>

呼び出し方

下記のようにmermaidタグで挟んで内容の部分にmermaidの記法に従って書けば図が作成されるようになりました。

{{<mermaid>}} 内容 {{< /mermaid >}}

mermaidで書けるもの

現在５種類の図が書けるようです。

フローチャート
シーケンス図
ガントチャート
クラス図
Gitのコミットグラフ

公式サイトのサンプルをほぼそのまま貼り付けて確認していきます。

フローチャート

ちゃんと表示されました。

出力イメージ

書き方

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

シンプルなサンプルですが書き方は直感的に分かるでしょう。

シーケンス図

続いてシーケンス図。これだけのものが専用のアプリなしで書けるのはすごく良いです。

出力イメージ

書き方

sequenceDiagram
    participant Alice
    participant Bob
    Alice->John: Hello John, how are you?
    loop Healthcheck
        John->John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail...
    John-->Alice: Great!
    John->Bob: How about you?
    Bob-->John: Jolly good!

ガントチャート

出力イメージ

書き方

gantt
        dateFormat  YYYY-MM-DD
        title Adding GANTT diagram functionality to mermaid
        section A section
        Completed task            :done,    des1, 2014-01-06,2014-01-08
        Active task               :active,  des2, 2014-01-09, 3d
        Future task               :         des3, after des2, 5d
        Future task2               :         des4, after des3, 5d
        section Critical tasks
        Completed task in the critical line :crit, done, 2014-01-06,24h
        Implement parser and jison          :crit, done, after des1, 2d
        Create tests for parser             :crit, active, 3d
        Future task in critical line        :crit, 5d
        Create tests for renderer           :2d
        Add to mermaid                      :1d

クラス図

experimentalですがクラス図が書けます。

出力イメージ

書き方

classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label

公式サイトから貼り付けただけなので意味を調べてませんが、何となく意味は分かるかと思います。

Gitのコミットグラフ

こちらもexperimentalですがGitのコミットグラフも書けます。
チームが採用しているブランチ運用ルールを説明する場面などに使えそうです。

出力イメージ

書き方

gitGraph:
options
{
    "nodeSpacing": 140,
    "nodeRadius": 10
}
end
commit
branch feature
checkout feature
commit
commit
checkout master
commit
merge feature

実際のGitの操作に近いので直感的にどう書くか分かりますよね。

おわりに

実際ブログの記事で使うことは少ないかなと思いつつ面白いの組み込んでみました。GitLabで使えると言うことで仕事では今後使っていきたいので、次回は書き方を調べてチートシートを作ってみようかな。