[Markdown] ダイアグラムを頑張って書くな [Mermaid]

この記事で、伝えたいことは下記2点です。

- Mermaidを活用して、少ない労力でダイアグラムを描こう
- Mermaid記法をゼロイチで書くのは大変なので、生成系AIを活用しよう

# はじめに

こんにちは。
システム設計やフローの整理において、フローチャートや状態遷移など、ダイアグラムを描く機会がありますよね。
みなさん、これらを書く時ってDraw.io やFigmaで、ちまちまアレコレ書いてませんか？
矢印や全体のレイアウトなど、簡単な図を書きたいのに、細かい調整が必要で面倒で苦労した記憶があります。

今回は、ダイアログを『自分で頑張って書く』のではなく、Mermaidと生成系AIを用いて、楽に書いてみましょう。


## Mermaidとは？

いくつかMarkdownでダイアグラムを書く方法はあるのですが、今回は`Mermaid` を紹介します。

https://mermaid.js.org/intro/

正確には、JSをベースにしたライブラリなのですが、ここではMarkdown記法の一つとさせてください。

類似のサービスで、`PlantUML` もいい感じにダイアグラムを書けるのですが、
Mermaidは、QiitaやGitHubのサービスなどでもレンダリング可能なため、こちらを紹介したいと思いました。

例えば、About Mermaidで紹介されている下記のダイアグラムを書いてみましょう。

~~~
```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop HealthCheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
```
~~~

下記のようにレンダリングされます。

```mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop HealthCheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
```

シーケンス図に限らず、Mermaidはダイアグラム全般を手広くカバーしています。
[先述のMermaid](https://mermaid.js.org/intro/)の公式を参考にしてもいいですし、Qiita公式の記事もあります。

https://qiita.com/Qiita/items/c07f3262d8f3b25f06c9

## 生成系AIを活用する

生成系AIは、イメージやテキストベースの説明は得意だと思うのですが、ダイアグラムの描画はまだ弱く、直接ビジネスに活用することは難しいと思っています。※ 自論です
一方で、Mermaid記法のテキストを経由することで、綺麗にダイアグラムを作成できます。


ためしに`ChatGPT 4o`で、OAuthのシーケンス図を出力して見ましょう。
まずは画像で出力してみます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/246336/bda4e176-2f38-3632-4e44-71d2e97adafa.png)

プレゼンなどでのイメージ図としては有用ですが、ドキュメントに用いるには大味な感じがしますね。

次に、Mermaid記法で出力してみました。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/246336/a795f80b-b8a2-7bcf-df88-07a9feecf684.png)

これを描画すると、、、

```mermaid
sequenceDiagram
    participant User as ユーザー
    participant Client as クライアントアプリ
    participant AuthServer as 認可サーバー
    participant ResourceServer as リソースサーバー

    User->>Client: クライアントアプリを使用してリソースへアクセス要求
    Client->>AuthServer: 認可コードを要求 (リダイレクト)
    AuthServer->>User: 認可要求 (ログイン + アクセス許可)
    User->>AuthServer: 認可を承認
    AuthServer->>Client: 認可コードを返却 (リダイレクトURL経由)
    Client->>AuthServer: アクセストークン要求<br>(認可コード + クライアント認証情報)
    AuthServer->>Client: アクセストークンを発行
    Client->>ResourceServer: アクセストークンを使用してリソース要求
    ResourceServer->>Client: 保護されたリソースを返却
    Client->>User: リソースを表示

```

めちゃくちゃいい感じです。
もし気になる部分が書き変える程度で済みそうですし、ドキュメント作業にも活用できるレベルだと思います。

## Mermaid Live Editor

手軽にMermaidを使うには、「Mermaid Live Editor」がオススメです。
URLでのシェアや、PNG等への出力、サンプルがあり、充実しています。

https://mermaid.live/

## VScodeで使うには

私は、一般的なMarkdownプラグインである下記を活用しています。

https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/246336/fd16d93e-8bfb-dc89-982e-093c45e50f15.png)

こちらもいい感じに描画できます！

## 最後に

私自身、過去にdraw.ioなどで頑張ってダイアグラムを書いていたのですが、細かいレイアウトの調整や、テキスト追加時の余白の調整などでかなり苦労しました。
細かく書くことは悪ではないのですが、少しの追記でレイアウトがズレまくるなど、ドキュメンテーションの本質ではないものに時間が割かれるのも考え物です。

同僚のYさんと `PlantUML`について話していて、諸々模索した結果、Mermaidめっちゃいいじゃんになり、布教したくなってこの記事に至ります。

これからみなさんがダイアグラムを書かなければいけない時に、Mermaidが選択肢に入ると幸いです！
よい Mermaid ライフを！