MermaidとMscgenのシーケンス図をプレビューするVisual Studio Code拡張を作りました（画像保存機能あり）
シーケンス図をテキスト表現する Mermaid や Mscgen を、Visual Studio Code でプレビューし、ファイルで保存する Visual Studio Code Extensionsを作成しました。
2022年7月頃：更新
プレビューイメージを、jpeg、png（背景透過する/しない）、SVGの各形式でのファイルまたはSVGでクリップボードに保存する機能を追加しました。Mermaidだけでなく Mscgenでも似た感じで動作します。
Mermaid の公式ライブラリを使う環境で、グラフの上下に巨大な余白が表示されてしまう、という課題がありますが、これも調整してあります。
v0.4.0 以降での対応です。
グラフ向けのコードが書かれたファイルを .mmd, または .msc の拡張子で保存し、VSCode で開いてください。コード上で右クリックからの Preview で表示します。
独自対応で、ファイルの入れ子処理にも対応してますので、上手く使うと、多数のシーケンス図の管理を多少改善されるかもしれません。
（少数ですが使い続けてくれている方々がいらっしゃいますので、不定期ですがMermaidやMscgenの更新に追従しています）
what is ‘Mermaid’, ‘Mscgen’?
上図のようなシーケンス図をテキストで表現するための取り決めです。詳細はこのサイトやネット情報をどうぞ。
日本業務の現場だとExcelやVisioで書いてしまうアレ達です。アレをテキストで表現しましょう、というものです。
Excelで書いてしまいがちなシーケンス図やフローチャート、ガントチャートをあえてテキスト表現する理由ですが、ずばり Git 時代に適した保守性だと考えています。
ExcelやVisioファイルで定義した内容を検索するのは一苦労ですし、修正が入った際に、それらを一括して修正するなんていう作業はまさに苦行です。テキストであれば、これらを Visual Studio Code のようなテキストエディタを用いてガッと修正することが出来ます。ちょー便利。
GitなどのVCSと併用する事で、業務仕様のバージョン管理と、プログラムコードのバージョン管理とを共存させることが出来ます。なにより、業務仕様の変化差分が一発で分かるという凄いことを、差分を可視化してくれるVCSでさらっと実現できるわけで、良い話です。
できれば、非エンジニアさんが業務プロセスを書き出す必要に迫られた際には（上場する前とか内部統制を高めたりする際には、必ず出会いますよね）、VS Code と Mermaid / Mscgen を使って、がしがしとテキストで業務を可視化して欲しいなぁ、と思いながら作ってます。
Mermaid
先のリンク先は、Mermaid のドキュメントページです。こちら、Markdownライクなシンプルな書き方で定義できるのと、表現する図のサポート範囲が広いので、業務現場だとこちらのほうが便利そうな気がします。ウェブサイトに組み込むための JavaScript API の例も公開されてるので、うまく使いましょう。
Mscgen
Mscgen はこちらから。
で、これを JavaScript でうまくやってくれるものを作ってくれた人のサイトが https://mscgen.js.org/ https://github.com/sverweij/mscgen_js です。今回のプレビュー拡張では、この mscgen_js を利用しているので、色表現などの機能は、まんま mscgen_js のが使えます。
how to install
ext install previewseqdiag-vscode で入ります。
VSCode は最新としてください。
Visual Studio Code Marketplace ではこちらで。
GitHub はこちらです。こちらから .vsix をダウンロード可能です。
off-line install
GitHub のサイトから.vsix をダウンロードしてください。依存してるもの一式入ってるのでこれでインストールが出来るはずです。
拡張を .vsix でインストール可能なので、off-line 環境でも導入可能なはずです。
how to use
サポートしているドキュメントの場合には、アクティブなドキュメントの右上に Preview と表示されるので、クリックしてください。
または、アクティブなドキュメントの上で右クリックです。
プレビュー用のウインドウは一つしか開きません。アクティブなドキュメントを変更するかテキストの内容が変更されると、プレビューを再描画します。
プレビューのレイアウトが崩れている場合には、VS Code のウインドウを広げて、プレビューを閉じた後、開きなおしてあげてください。
about implementation
VS Code の Extensions が公開してる変更イベントを拾い、標準で実装されている vscode.previewHtml コマンド（Markdownプレビューが使ってる）を利用してプレビュー用の HTML を生成して単純に投げ込んで表示させてます。
で、この実装だと、イベントが発火するたびにDOMがまるっきり再作成なので画面がクリアされてしまいプレビュー画面がチカチカとフリッカーします。非常にきついです。
DOMを維持して外から差し替える方法を考えてはみたのですが、 vscode.previewHtml を使う限り（内部でWebViewとして動作を制限するような動きをする関係で）あまり良い手が浮かばず。
なので、雑なのですが RxJS (npm の rx)を使って、イベントを debounce してます。ハードコード決め打ちの 500ms ですが悪くない感じです。
同じ理由で、プレビューを SVG や PNG でダウンロードする機能の実装は見送っています。プレビューしてるHTMLの中でSVGをダウンロードするように書いてみたのですが、リンクがフックされ書き換えられるのでダウンロードできず。また、だったら、拡張のなかで、プレビューにHTMLを渡す前の段階で SVG 化した後にファイル保存ダイアログを出してあげればよいのでしょうが、ちとわからずで、時間のかかる作り替えなので断念。
VS Code で表示されるプレビュー画像の下部に公式サイトのデモサイトへのリンクを記載したので、そこで書いたテキストをコピペしてあげれば、SVGなりPNGなりでダウンロード出来ます。
最悪は、VS Code の画面をキャプチャしてペイントで切り出せば、なんとかなります。インターネットに出られない環境でも、なんとかはなるはず。
tips
Mermaid は標準で dark / light の CSS が提供されていたので、VS Code のテーマに合わせて自動で切り替えます。これが嫌な場合、例えば以下のユーザー設定で強制することが可能です。（README にも書いてあります）
"previewSeqDiag.mermaid.fixedStyle":"forest",
"previewSeqDiag.mermaid.fixedBackgroundColor":"#ffffff",forest (light向けの緑色の描画)で図を描画し、その背景を #ffffff で塗りつぶします。
Mecgen_js は、既定で背景が白を強制していて、dark / light テーマがないので、常に白背景で書いてます。こちらの場合、描画スタイルを指定できるようにしました。
"previewSeqDiag.mscgen.fixedNamedStyle": "fountainpen",スタイルの指定は、https://mscgen.js.org/embed.html#named-styles を参照のこと。今回のプラグインでの既定値が cygne になってるのは、私の好みです。
known issue
当方の開発環境が Windows 10 で、それ以外では検証していません。他のplatformで問題あれば GitHub の issue で教えてください。
for you
シーケンス図を差分管理したい、マークダウンの中には書きたくない、というケースで、画像化、SVG化したいケースでは、使い勝手良いとは思います。何か機能改善あればどうぞご連絡ください。
for CI
Twitter でコメントがあったので。
Mermaid は CLI が用意されているので、CIプロセス上で生成が可能です。
MscGen も歴史あるので、やりようは何かあります。
