gitbook-plugin-mermaid-2の導入

久しぶりに完全新規でgitbook + mermaid.js環境を作ったらハマったのでメモ

mermaid.jsが素晴らしいけどなかなか使ってる人見かけないので実例晒す を書いた頃に作ったプロジェクトは以下の構成

• gitbook-plugin-mermaid : "0.0.4"
  • ただし、ganttとか使いたかったので手動でmermaid.js本体の 0.4.0 を当ててた。
• gitbook-cli : "1.0.1"

で、完全新規でつくることになったので前回と同じ勢いで gitbook-plugin-mermaid をnpmで入れると、0.0.9 になった。

Haroopad や既存の gitbook + mermaid 環境で作っていたドキュメントが大量にあったので、それを流用しようとすると、見事にレンダリングされなくなった。なんで？

gitbook-plugin-mermaid の変更

0.0.4当時では、mermaidを記載する方法はmarkdownのコードとして記載する方法だった。

　```mermaid

　graph TD;
　 A-->B;
　 A-->C;
　 B-->D;
　 C-->D;
　```

これが、最新の0.0.9ではこうなっている

> ```
{% mermaid %}
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
{% endmermaid %}

詳細 : https://github.com/JozoVilcek/gitbook-plugin-mermaid

確かに便利だけど、Haroopadや既存の資産との互換性も保ちたい・・・

gitbook-plugin-mermaid-2

ググるとこっちの方が上位に出る。
記法が古い gitbook-plugin-mermaid と同じで、互換性も高い。

Good

既存との互換性。

コードブロックなので、markdown的にも直感的だし、mermaidが無くてレンダリング出来ない場合の体裁もマシ。

あと、 book.json の pluginsConfig にテーマ設定を書けるので楽。

book.json

{
    "plugins": [
       "mermaid-2"
    ],
    "pluginsConfig": {
      "mermaid-2": {
         "theme": "forest" 
      }
    }
}

初見でハマったところ

どこが悪さしているかちゃんと追っていないけど、リンクのテキストにダブルクォーテーションが入っているとレンダリングに失敗する。
他の記号でも、前は動いてたけど現在はNGなものがあるかもしれない。

OK

NG

まとめ

2016/02/24 現在でそれぞれのプラグインをインストールして落ちてくるmermaid.jsのバージョンは以下の通り。

• gitbook-plugin-mermaid : 0.5.6
• gitbook-plugin-mermaid-2 : 0.5.8

既存や他のエディタとの互換性&最新が使えるという点を考えると、2 の方でいいかもしれない。

その他

少し前だが、本家が大幅にイメチェンした。
https://knsv.github.io/mermaid/

ライブエディタが意外と凝っている。とりあえずどんなもんか見たい人はオススメ。ハッシュ化してURLにできるので、やろうと思えばこのまま共有もできる。
http://knsv.github.io/mermaid/live_editor/

追記(2017/02/28)

新規プロジェクトで作り直したところ、gitbook-cli側でpluginの 'head:end' がdeprecatedになった影響で、gitbook-plugin-mermaid-2はうまく動かなくなっていました。
互換性は諦めて、gitbook-plugin-mermaidを使うべきかなぁ。