テキストのみでシーケンス図を描画するmermaid.jsをWordPressで使う

余計な描画ツールを使わずに、エディタの中でテキストのみでシーケンス図やフローチャートを表現したいと思い、mermaid.jsの適用を試しました。

mermaid.jsとは

mermaid.js は、Markdownに似たテキスト記法でフローチャート・シーケンス図・ガントチャート等を描画できるJavaScriptライブラリです。

テキストベースで図を管理できるため、Gitでの差分管理が可能になること、ドキュメントの中に図を直接埋め込めること、描画ツールを別途起動する必要がないことがメリットです。特に技術ドキュメントを書く場面では、図のメンテナンスコストが大幅に下がります。

WordPressへの導入

やりたいことは単純で、以下2行で初期作業は完了するはずです。

<script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>

しかしWordPressの癖で一筋縄にいかない部分がありました。

エスケープ問題

mermaidでは --> のような記号が出てきますが、WordPressのページ描画時にエスケープ処理されて --> となってしまいます。これではmermaidが正しくパースできません。

サイト全体のエスケープ処理を止める方法もありますが、mermaidで表示したいコンテンツはごく一部です。そのためだけにセキュリティ処理を止めるのは気持ちが悪い。

対処法: codeタグの挙動を活用する

WordPressの code タグはエスケープ処理の挙動が通常のタグと異なります。これを利用して、<code class="mermaid"> で描画エリアを表現するアプローチを取りました。

具体的には以下の構成で適用しています。

1. jsファイルの読み込み — CDNリンクを利用し、テーマファイルのfooter部分に記載。ファイル管理の手間を省くため
2. エスケープ抑止関数 — functions.php にmermaid記法をエスケープせずにそのまま出力する関数を記載
3. 描画エリアの指定 — 本家サンプルでは <div class="mermaid"> を使うが、今回は <code class="mermaid"> とする

動作サンプル

フローチャートの例:

graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]

シーケンス図の例:

sequenceDiagram
    Client->>Server: Request
    Server->>Database: Query
    Database-->>Server: Result
    Server-->>Client: Response

このように、テキストエディタだけでそれなりに読みやすい図が出力できます。

mermaid以外の選択肢

テキストで図を描けるライブラリとしては js-sequence-diagrams もあります。ただしGitHubのStar数ではmermaidが圧倒的に多く、対応する図の種類も豊富なので、特にこだわりがなければmermaidを選んでおけば間違いないと思います。

まとめ

テキストベースの図はドキュメントのメンテナンス性を大きく改善します。WordPressではエスケープ処理との相性が悪い部分がありますが、code タグの挙動を活用することで対処可能です。

参考: mermaid - GitHub / Mermaid Live Editor