Zennが mermaid.js によるダイアグラム表記に対応したので試す

Zenn で mermaid.js によるダイアグラムが表現できるようになりました。ZennのMarkdown記法一覧も更新されています。この記事では mermaid.js を使っていくつかの図をかいてみます。

• 基本的な使い方
• mermaid.jsのドキュメントを見ながらいろいろな図を書いてみる
• 各種エディタでプレビュー

このあたりを記録します。

基本的な使い方

コードブロックで囲んで言語名を mermaid とすることで、自動的にレンダリングされます。いまのところ、mermaid.jsの8.10.xを読み込んで使っています。

```mermaid
graph TB
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
```

は以下のように表示されます。

javascript などの言語がソースコードハイライトされるのと同じように、mermaidとなっていた場合は図がレンダリングされる動きです。ただしmermaidの場合は図のかわりに元のソースを表示する手段がないので、ソースコードも併記したい場合は上で示した例のように~~~で囲むか、シンプルに

```text
graph TB
  ...
```

としてください。

グラフの方向

図によっては伸びる方向を指定できるものがあります。Zennではmermaid.jsによる図の横幅がコンテンツ領域を超えないように設定しているので、大きなグラフは横長にするよりは縦長にするほうがおすすめです。例えばフローチャートではgraph TB（Top to Bottom）やgraph LR（Left to Right）を指定できるのですが、 graph LR を指定してどんどんエッジを加えていくと…

このように図の文字やノードが小さくなります。もちろん場合によっては、左右に展開して一覧性をよくしたいというケースもあるので最後は執筆者の判断に委ねられます。記事はスマートフォン端末でも見られる可能性がある、という点だけご注意ください。

initディレクティブ

mermaid.js では initディレクティブ（Directives）で初期化パラメータを追加できます。ユースケースとしては、グラフのカラーテーマを変える、が考えられます。詳細は公式ドキュメントのDirectivesを参照してください。ここではテーマを変えてみる例を示します。

```mermaid
+%%{init: { 'theme': 'forest' } }%%
graph TB
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
```

先程とグラフの内容は同じですが、カラーテーマが変わっていることがわかります。なおディレクティブですが、比較的新しい機能であり、まだまだ破壊的変更がありえます。多用は控えることをおすすめします。

いろいろな図を書いてみる

ドキュメントを眺めつついろいろな図をかいてみましょう。

フローチャート

ノードとエッジをもついわゆるグラフです。その名のとおりフローチャートを書いたり、あとは例えばダイクストラなどのグラフアルゴリズムの表現でも役に立つかもしれません。

シーケンス図

業務プロセスやITシステムにおける通信機器同士のやりとりを表現するのに役立ちます。あみだくじを書くときにも使えるかも…。

クラス図

最近は利用頻度は減った感触がありますが、オブジェクト指向言語におけるクラス同士の関係を表現するのに役立ちます。コードレビュー依頼で一緒に添えるとレビュアーが喜ぶかもしれません。

状態図

こちらもWebシステムだとステートレスな設計も増えて登場頻度は減った感触ですが、業務設計におけるユーザーの状態（ログイン前、支払い済み、退会済み、など）であったり、組み込みシステムなどでの活用がありそうです。

ER図

なんだかんだでリレーショナルデータベースは使われ続けると思うので、在宅ワークも増えつつある現場では認識合わせなどでも役に立ちそうです。

Gantt

エディタでプレビューする

いろいろな図を表現できることがわかりました。あとは記事へ書いていきます。他の記法と基本の流れは同じです。エディタで記載して、プレビューで意図どおりにレンダリングされるか確認します。

zenn-cli preview

GitHub連携している場合はzenn-cliを使ったプレビューが便利です。下書きの記事にmermaid.jsの図をかいて、プレビューしてみましょう。まずは、執筆している作業ディレクトリでzenn-cliを最新版にアップグレードします。

yarn add zenn-cli@latest

その後、文法にのっとってmermaid.jsの図を書きます。

## ER図

なんだかんだでリレーショナルデータベースは使われ続けると思うので、在宅ワークも増えつつある現場では認識合わせなどでも役に立ちそうです。

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        string name
        string custNumber
        string sector
    }
    ORDER ||--|{ LINE-ITEM : contains
    ORDER {
        int orderNumber
        string deliveryAddress
    }
    LINE-ITEM {
        string productCode
        int quantity
        float pricePerUnit
    }
```

プレビューします。

yarn zenn preview
👀Preview on http://localhost:8000

http://localhost:8000 で mermaid.js の図がレンダリングされていれば成功です。

Zennのオンラインエディタ

ブラウザのエディタでも確認してみます。

こちらでもプレビュー表示できてそうです。

VSCode Zenn Editor Preview

negokazさんにより公開された VSCode 拡張も試しましょう。

プレビュー表示で mermaid.js の図がレンダリングされています。ありがとうございます。仕組みをあまりよくわかっていないのですが、内部的に http://localhost:8000にアクセスして表示しているでしょうか？とすると、手元の zenn-cli が最新版になっていればプレビューも自動的に新しくなってくれそうです（間違っていたらご指摘ください！）。

おわりに

Zennで新しく対応した mermaid.js を使ってみました。まだまだ発展途上のライブラリであり、今後も新しい図が追加されたり、文法の破壊的変更が入ることがありえますが、Zennで執筆する記事のクオリティ向上に寄与できれば幸いです。なにかフィードバックがありましたら以下のようにお願いできればと思います。

• 文法などを確認したい
  • 👉公式ドキュメントが役に立つはずです
• なんか動作が変かも
  • 👉mermaid-js/mermaid の Issue を探すと解決策が見つかるかもしれません
• Zennの問題かも？またはどうしてもわからない
  • 👉zenn-dev/zenn-communityにて起票いただけますと幸いです