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にて起票いただけますと幸いです
