前置き
mermaid.js使ってmarkdownで設計書書いたら楽だよ って記事を書いて以降、もっぱら設計書はGitbookで書いている。
最近は GitLab Pages に CDしてそのままアクセス制限ありで限定共有することで、とても作業効率が上がっていて嬉しい限りである。
ただ、難点なのが、 Gitbook用のmermaid.jsのプラグインが軒並みメンテされておらず、 Gitbook3で動かない ものや、動いても mermaid.jsのバージョンがv7系までしか対応してない こと。
最近のmermaid.js
一方、mermaid.jsの方はv8系になって対応する図の種類が一気に増えた。
かつては、
- Flowcharts
- Sequence diagrams
- Gantt diagrams
だったのが、v8(v8.5)で増えたのが、
- Git graph
- Class diagrams
- Entity Relationship Diagrams
- State diagrams
- Pie chart diagrams
※一部、まだ試験的実装のものがあります。
という豪華さ。
詳しくは、以下の記事が日本語でまとめてくれてるのでありがたく参照しよう。
あとあと、既存の図もだいぶ進化してる。例えば、 Sequence diagrams に autonumber 機能が増えた。
シーケンス番号がでると、図の下に番号付きリストで説明書いていく事ができる。Gitbookで設計書書くときにこの上なく便利。
こんなに便利なのにGitbookで使えないのくやしい！
それでは Plant UML ではダメなのか？
Plant UMLもかなり良い。しかもGitbookのプラグインもある。
ただ、メインのライブラリがJavaであり、jarファイルをいちいち取ってこないといけないことが、環境構築やCDの構築の際にちょっと手間になる。
nodeのdockerイメージ一発どーんで上手くいかないので、docker-compose挟んでPlant UMLのレンダリングサービスのdockerイメージを横で走らせるとか。
可能なんだがめんどいシリーズ。
プラグイン作った。
無いなら作れ。って事で、npmで公開されてる中で一番良さげな gitbook-plugin-mermaid-gb3(これでも最終更新3年前...)をforkさせてもらって、作った。
gitbook-plugin-mermaid-newface
名前がだいぶ脳死だが、ゆるしてほしい。
(実際、実案件で使うので夜中に突貫で作ったのでゆるしてほしい。)
Class Diagram だけが、レンダリング前に変にエスケープされて渡ってくるのでエラーになるが、その他はちゃんと描画できてる。すばらしい。
修正ポイント
mermaid.js のバージョンを上げればそれでいいでしょと思ったが、ほぼほぼ書き換えることになった。
mermaid.js の変更によるもの
- 初期化メソッドが
mermaid.init()からmermaid.initialize()に変更。configも実質必須。 - cssはlinkで読込ではなく、mermaid.jsの内部で動的に適用される(
themeを初期化メソッドで指定できるようになったため)。
Gitbook の変更によるもの
- 元は、gitbookの
hooks.pageイベント時に正規表現でコードブロックをひっかけて処理していたが、それだと他のライプラリとコンフリクトする(gitbook-plugin-prismとか)。blocks.codeイベントだとコードブロックだけ流れてくるので、ここでlanguageの値を見て処理するがベター。- こんなかんじ
- ちなみに、
blcoks.codeイベントの引数はこんな感じ。
{
"body": "sequenceDiagram\n participant mcu as MCU\n participant flash as FlashROM\n participant sensor as Sensors\n participant cloud as Cloud\n\n mcu->>+cloud: get hoge\n cloud-->>-mcu: hoge\n\n mcu->>mcu: check hoge\n\n alt fuga\n mcu->>+flash: Write hoge\n flash-->>-mcu: Write OK\n end\n",
"kwargs": {
"language": "mermaid"
},
"args": [],
"blocks": []
}
- ページのhtml側で読み込む plugin.js のほう、引数で渡ってくる
gitbookオブジェクトが便利で、gitbook.state.configにbook.jsonの設定の内容が入ってくるので、これで処理分けられる。特にpluginsConfigとか。
終わりに
開発現場から Word / Excel の仕様書を駆逐しよう！！！！！
2021年1月30日追記
ページロード関連で描画されない問題があったのと、PDFで描画されない問題があったので、思い切って mermaid-cli を使うように変更した！
自画自賛だけどめっちゃ快適になった！！！
