会社でフロー図を書こうと思って PlantUML と mermaid.js を比べてみる #HTML

ずっと PlantUML でクラス図を書いてきたけど、書きたいフロー図が PlantUML で書けなかったので mermaid.js を触ってみた。
会社に導入するって観点で比べてみる。

PlantUML は結構な量書いたので慣れているけど mermaid.js は数日触ってみた程度なので、理解度が違うのは勘弁で。

概要

サイト紹介とサンプル紹介

PlantUML

公式サイト

.pumlというファイルを書いて描画させるとこんな図になる

クラス図

シーケンス図

アクティビティ図

他にもステートマシン図とかユースケース図とかも書ける

mermaid.js

公式サイト

.htmlファイルを書いて描画させるとこんな図になる

クラス図

フローチャート

他にもガントチャートとかも書ける

出来ること

実用する際に融通が利きそうなこと、ネックになりそうなこと

PlantUML

提供されている図はどれも結構凝ったことが出来る印象
- 矢印にテキストを書いたり、クラス図中のテキストの字の色を変えたりも可能
別の.pumlファイルを読み込めるのでファイル分割が可能
特定の記述があるとＸＸ図のコードだと判断され描画されるので、１枚に複数種類の図を併記することは出来ない

mermaid.js

.htmlなので図の部分以外の箇所の融通がすごい利く
フロー図ではclickが設定できた
- 図のパーツそれぞれにマウスオーバー時のテキスト表示、リンク化、onclickが設定できる
クラス図はあんまり得意じゃあないって感じがした
- 見た目の整形もあまりできなそうだし、clickも出来なかった
ファイル分割は出来ない
- .htmlなのでどうにでもなるけど

試しやすさ

初めて触ってみる際の準備や手間について

PlantUML

使ったことないけど、オンラインエディタがある
ローカルに準備をしようと思うと.jarとGraphvizが必要になるし、プレビューも少し面倒

mermaid.js

こちらも使ったことはないけど、やっぱりオンラインエディタがある
ローカルだと CDN で mermaid.js を読んでブラウザで見る方法があり、PlantUML に比べると相当楽

最低限これだけを書いてsimple.htmlとしてブラウザで開けば良い。（chrome でのみ確認）

simple.html

<div class="mermaid">
graph LR
    A --> C
    B --> C
    B --> D
    C --> D
</div>

<script src="https://unpkg.com/mermaid/dist/mermaid.min.js"></script>

エディタとローカルプレビュー

自分が書いたり確認したりする時のこと

PlantUML

IntelliJ IDEA に PlantUML integration というプラグインがあり、それでプレビューも出来る
新規作成で図の種別が選べて、出来たファイルに最初からサンプルが書いてあるので、割とある程度の物は適当に書ける

他にもエディタは色々あるけど、僕はこれ以外紹介できない

mermaid.js

IntelliJ IDEA にプラグインはなさそうだった
Haroopad ってエディタが設定が不要でプレビューも出来るらしい
けど結局は.htmlとブラウザで良いので僕は vim で書いている

オンラインプレビュー

テキストベースだから git で管理したいしレビューもちゃんとやりたいので、GitHub のソースコードを楽にプレビューできないといけない

PlantUML

chrome 拡張に PlantUML Viewer というのがある
そういえば前に紹介記事を書いた
- GitHubで差分を見る時にPlantUMLを描画させる

mermaid.js

パッと探した限りだと、GitHub 上に表示された.htmlコードをプレビューする chrome 拡張とかは見つからなかった
- ありそうだけどな？
github pages があるけど、あれは master ブランチにあるものしか閲覧できないので、マージ前のレビューとしては使えない

セキュリティ

会社のシステムやプロセスについて記述する際の注意

PlantUML

chrome 拡張で描画をするのは外部にソースを送って画像を送り直して貰う構成のはずなので、企業秘密を含んでいるソースで利用するのは不適切
オンラインエディタも同様

mermaid.js

こちらのオンラインエディタもおそらく同様
github pages は private repository であっても閲覧制限がかかっているわけではないのでこれも厳密に考えると利用するべきではない

ドキュメント閲覧

書き上がったドキュメントを周知する

PlantUML

セキュリティの問題も考えると、ローカルで画像として保存したものを社内のポータルや社内チャットで共有するという形になりがち
それかソースの改版の際に都度ローカルで画像を作り、それを一緒にコミットし、閲覧は GitHub の private repository で行う
周知相手が同じコンポーネントのエンジニアだけなら、git でローカルのソースを更新して各々エディタで確認するという方法もある
- クラス図等であればソースと一緒に自然と更新されるしエディタで開くのも妥当
- が、プロセスを定めた図やチートシート等のプロダクトコードと関係ない図だと微妙

mermaid.js

gitlab pages というのがあるらしい
- 社内に gitlab が立ってるので試そうと思ったんだけど、どうも github pages と比べて格段にめんどくさそう
.htmlでしかないので、適当な検証用 web サーバを間借りして置いちゃうことが出来るかも知れない

まとめ

mermaid.js はちょっとだけとは言え、両方を触ってみたので総括してみる

PlantUML

クラス図は圧倒的にこちらが得意
includeが使えるのでファイル分割もこちらが得意
少し導入や閲覧で下げちゃったけど、プロダクトコードと一緒に管理するクラス図やシーケンス図ならとても良いと思っている

mermaid.js

.htmlという点を活かすと出来上がる資料の融通はかなり利きそう
マウスオーバーで補足説明を添えたり、別資料へのリンクが出来るのはかなり良さそう
冒頭で述べた書きたいフロー図は思った以上にイイカンジで実現できそうなので、もう少し馴染んだらまた紹介したい

触ってみた感じだと案外得意不得意がはっきりしているので、必ずしもどちらかだけに決めることもないかな、というのが今の印象。