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が指定された場合は
%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
%%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%
これらは統合されて1つのDirectiveとなります。
{
"logLevel": "fatal",
"theme": "dark",
"startOnLload": true
}
上の例では統合の結果、"logLevel"
が"fatal"
に設定されました。
Directiveを適用した例
次のDirectiveを適用して[A]-->[B]のグラフを書いてみます。
%%{
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以上)。
標準の設定だと、
%%{
init:
"flowchart": {
"defaultRenderer": "dagre",
"curve": "basis"
}
}%%
これをelkjsに変更すると
%%{
init:
"flowchart": {
"defaultRenderer": "elk",
"curve": "basis"
}
}%%
あとは"curve"をd3.jsのcurveオプションから設定してやればそれなりにいい具合になることがあります1。
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なんですって。やっぱすげぇなあのプロジェクト。 ↩