gitbook-plugin-mermaid-2の導入 #Markdown

久しぶりに完全新規で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なものがあるかもしれない。

graph TD;
  A-. ほげ<br>"ho"ge .->B;
  A-->C;
  B-->D;
  C-->D;

graph TD;
  A-. ほげ<br>hoge .->B;
  A-->C;
  B-->D;
  C-->D;

まとめ

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を使うべきかなぁ。