mermaidらくちん!

Qiitaで記事を書いていると「あー、スクショ撮るのめんどい」とか「あー、これフロー図書いたほうがわかり良いわ」とか出てきます。スクショはクリップボードから直接貼り付けができるのでとても楽になりました。で、図形描画、特に「なんとかとなんとかを矢印で結んで～」といったものは今まで結構とっつきづらいイメージがあったのですが、mermaid(https://mermaid.js.org/) のmermaid記法が使えるとのことで、使ってみました。
めっちゃらくちん!
というわけで、基本的なコマンドとかを本家からピックアップしてまとめようというのが本記事の主旨です。

各ダイアグラムについて

mermaidが対応しているダイアグラムを表にしてみました(リンク先は本家ドキュメント(英語))。

ダイアグラムの名前	日本語名称	主な用途	対応状況
Flowchart	フローチャート	流れ図有向・無向グラフ	正式対応
Sequence Diagram	シーケンス図	UML	正式対応
Class Diagram	クラス図	UML	正式対応
State Diagram	状態遷移図	UML	正式対応
Entity Relationship Diagram	ER図	データベース設計	正式対応
User Journey	ユーザーエクスペリエンス図(?)	(これなんだろ)	正式対応
Gantt	ガントチャート	タスク管理	正式対応
Pie Chart	円グラフ	数値グラフ	正式対応
Quandrant Chart	4象限マトリクス	分析図	正式対応
Requirement Diagram	要求図	SysML	正式対応
Gitgraph (Git) Diagram	Gitグラフ	コミットグラフ	正式対応
C4C Diagram (Context Diagram)	C4モデルのコンテキスト図	C4モデル	Experimental
Mindmaps	マインドマップ	分析図	Experimental
Timeline	タイムライン	時間変化表現	Experimental
ZenUML	ZenUML	UML	Experimental

User Journey いったい何者なの……?

コメントとオプションについて

mermaidにはコメント機能があります
コメント自体は%%から始まる行がコメントになるみたいです。
例えば、下のコードをmermaidにすると

%% これはコメントです。
flowchart TB
    %% ノードの設定
    root(hoge)
    A[piyo]
    B[fuga]
    %% 枝の設定
    root-->A
    root-->B

ばっちり図だけになってますね。

また、Qiitaでは有効にならないようですがオプションの命令セットがあります。

mermaid.jsのDirective

Directiveについてざざっと斜めに見ていきましょう。

Directiveの宣言

Directiveはmermaidグラフの宣言の直前に表記します。
%%{directive_text}%%というようにパーセント記号2つを重ねた中に命令文を書いていきます。
directive_textの部分はJSONになります。キーワードinitまたはinitializeから始まります。
例えば次のように、initおよびinitializeから始まる2つのdirective_textが指定された場合は

directiveの例

%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
%%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%

これらは統合されて1つのDirectiveとなります。

initとinitializeを統合した結果

{
    "logLevel": "fatal",
    "theme": "dark",
    "startOnLload": true
}

上の例では統合の結果、"logLevel"が"fatal"に設定されました。

Directiveを適用した例

次のDirectiveを適用して[A]-->[B]のグラフを書いてみます。

適用するDirective

%%{
  init: {
    "theme": "dark",
    "fontFamily": "monospace",
    "logLevel": "info",
    "flowchart": {
      "htmlLabels": true,
      "curve": "linear"
    },
    "sequence": {
      "mirrorActors": true
    }
  }
}%%

オプション設定なしだとこうですが

オプション設定を入れると、ダークモードになりました。フォントも等幅フォントになってますね。
Qiitaで使っているmermaidは(2023年06月10日現在)Version8.14.0のようですので、最新版(10.2.3)とはオプションが違う所もあるかもしれません。

Directiveの使いどころ

「別に色が変わってもうれしくない」というお話はあるでしょう。でも、特に複雑なグラフ(点と点を線でつないだやつね)を定義すると、しばしば線が暴れる(というかなんでこんなに線がとっ散らかってんだ?)となることがあります。
そういう時にはレンダラーをdagreベースのものからelkベースのもの(elkjs)に変更してやると解決することがあります(ただしVersion9.4以上)。

標準の設定だと、

レンダラーがdagre

%%{
    init:
    "flowchart": {
        "defaultRenderer": "dagre",
        "curve": "basis"
    }
}%%

これをelkjsに変更すると

レンダラーをelkjsに設定

%%{
    init:
    "flowchart": {
        "defaultRenderer": "elk",
        "curve": "basis"
    }
}%%

あとは"curve"をd3.jsのcurveオプションから設定してやればそれなりにいい具合になることがあります¹。
curvesのオプションは

basis
bumpX
bumpY
cardinal
catmullRom
linear
monotoneX
monotoneY
natural
step
stepAfter
StepBefore

が指定できるということです。
その他カスタムカーブの設定はd3-shapeプロジェクトのshapesのページからどうぞ。

mermaid.jsを使える環境

Qiita以外でもmermaidは使えます。Visual Studio Codeの拡張機能なんかを入れると手元のmarkdownでお絵描きができてとても良いです(PlantUMLとどっちがいいかはわかんない)。
ここではmermaid.js公式で「ここで使えるよ」というサイトやサービスを一覧で紹介……しようかと思ったけれども数が多くて挫折した……
なお公式のページはこちら。

QiitaのユーザーだとEditor Pluginsあたりをみるとありがたいのではと思います。あとはsphynx拡張とかもあるんですね。

Visual Studio Code拡張

とりあえず

入れれば幸せになれると思います。
あとは

みたいな図がもっとバシッとかけるようになってくれればいいなぁ(願望)。

内部的に使っているのはd3.jsなんですって。やっぱすげぇなあのプロジェクト。 ↩