mermaidを使って図を楽に作ろう！

## はじめに

この記事はHRBrain Advent Calendar 2022 カレンダー2の8日目の記事です。

https://qiita.com/advent-calendar/2022/hrbrain

こんにちは！株式会社HRBrainでエンジニアをしているZamaです。

プロダクト開発の様々な場面で色々なドキュメントを作成すると思いますが、正直大変だったり面倒くさかったりしますよね...
しかし実装前の認識合わせや既存の設計や機能の確認などにドキュメントは書いておいた方がいいのも事実。
そこでドキュメント作成において図を楽に追加できるmermaidを紹介します！

※以下の内容は2022年12月8日時点のものになります。

## mermaidとは

[mermaid](https://mermaid-js.github.io/mermaid/)とは、MarkdownにインスパイアされたJavaScriptベースのダイアグラム・チャート作成ツールです。
Markdownのコードブロック内に図をテキストとして書いていきます。
[GitHub](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/)、[Qiita](https://qiita.com/release-notes#2022-04-12)、[Notion](https://www.notion.so/ja-jp/releases/2021-12-23#%E3%82%B3%E3%83%BC%E3%83%89%E3%83%96%E3%83%AD%E3%83%83%E3%82%AF%E5%86%85%E3%81%A7%E3%83%95%E3%83%AD%E3%83%BC%E3%83%81%E3%83%A3%E3%83%BC%E3%83%88%E3%82%84%E5%9B%B3%E3%82%92%E4%BD%9C%E6%88%90)は標準で対応していて、Visual Studio Codeには[拡張機能](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)があります。

百聞は一見に如かずということで、いくつか例を見ていきましょう！

### フローチャート

まずは[フローチャート](https://mermaid-js.github.io/mermaid/#/flowchart)です！
開発タスクのステータス遷移を作ってみました。
簡単かつ楽ですね。

上がMarkdown内の記述、下がそれを元に生成された図になります。

```markdown
flowchart TD
    A[ToDo]--実装開始-->B[Implementing]
    B--実装完了 PR作成-->C[Waiting For Review]
    C--レビュー開始-->D[In Review]
    D--Approved テスト環境作成-->E[Ready To Test]
    E--テスト開始-->F[Testing]
    F--テストOK-->G[Tested]
    F--テストNG-->H[Test Failed]
    H--修正開始-->B
    G--PRマージ-->I[Done]
```

```mermaid
flowchart TD
    A[ToDo]--実装開始-->B[Implementing]
    B--実装完了 PR作成-->C[Waiting For Review]
    C--レビュー開始-->D[In Review]
    D--Approved テスト環境作成-->E[Ready To Test]
    E--テスト開始-->F[Testing]
    F--テストOK-->G[Tested]
    F--テストNG-->H[Test Failed]
    H--修正開始-->B
    G--PRマージ-->I[Done]
```

### シーケンス図

次は[シーケンス図](https://mermaid-js.github.io/mermaid/#/sequenceDiagram)です！
ユーザー登録時の処理の流れを簡単に作ってみました。
最初に登場人物を、それから処理をつらつらと書いていくだけです。

```markdown
sequenceDiagram
    participant User
    participant App
    participant Server
    participant Database

    User->>App: ユーザー登録ページを開く
    App->>User: ユーザー登録フォームを表示する
    User->>App: メールアドレスとパスワードを入力し、登録ボタンを押す
    App->>Server: POST ユーザー登録API
    Server->>Database: Insert メールアドレス, パスワード
    Database->>Server: OK
    Server->>Server: ログイン処理
    Server->>App: 200 OK
    App->>User: ダッシュボードページを開く
```

```mermaid
sequenceDiagram
    participant User
    participant App
    participant Server
    participant Database

    User->>App: ユーザー登録ページを開く
    App->>User: ユーザー登録フォームを表示する
    User->>App: メールアドレスとパスワードを入力し、登録ボタンを押す
    App->>Server: POST ユーザー登録API
    Server->>Database: Insert メールアドレス, パスワード
    Database->>Server: OK
    Server->>Server: ログイン処理
    Server->>App: 200 OK
    App->>User: ダッシュボードページを開く
```

### ER図

最後の例は[ER図](https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram)です。
会社 - 部署 - 従業員というモデルを作ってみました。
配置を自由にできないという問題はありますが、社内資料としては十分なレベルです。

```markdown
erDiagram
    COMPANY ||--|{ DEPARTMENT: has
    EMPLOYEE ||--|{ COMPANY: belongsTo
    EMPLOYEE ||--|{ DEPARTMENT: belongsTo
    COMPANY {
        string name
        string address
        string telephoneNumber
    }
    DEPARTMENT {
        string name
    }
    EMPLOYEE {
        string firstName
        string lastName
        date birthDay
    }
```

```mermaid
erDiagram
    COMPANY ||--|{ DEPARTMENT: has
    EMPLOYEE ||--|{ COMPANY: belongsTo
    EMPLOYEE ||--|{ DEPARTMENT: belongsTo
    COMPANY {
        string name
        string address
        string telephoneNumber
    }
    DEPARTMENT {
        string name
    }
    EMPLOYEE {
        string firstName
        string lastName
        date birthDay
    }
```

### その他

他にも以下のようなものがあります！
聞いたことがないものもありますね...

- [クラス図](https://mermaid-js.github.io/mermaid/#/classDiagram)
- [状態遷移図](https://mermaid-js.github.io/mermaid/#/stateDiagram)
- [ユーザージャーニー](https://mermaid-js.github.io/mermaid/#/user-journey)
- [ガントチャート](https://mermaid-js.github.io/mermaid/#/gantt)
- [円グラフ](https://mermaid-js.github.io/mermaid/#/pie)
- [要求図](https://mermaid-js.github.io/mermaid/#/requirementDiagram)
- [Gitのブランチ・ツリー](https://mermaid-js.github.io/mermaid/#/gitgraph)
- [C4モデル](https://mermaid-js.github.io/mermaid/#/c4c)
- [マインドマップ](https://mermaid-js.github.io/mermaid/#/mindmap)

## まとめ

Markdown内に図を作成できるmermaidをご紹介しました！
文章やリスト、テーブルだけでは表現に限界があるので、こういった図を追加できるとドキュメントがより良いものになりますね！
しかも簡単です！
また、テキストとして定義するので、Gitで管理すればバージョン管理や差分の確認もできます。
ぜひ業務で使ってみてください！

## We are hiring!

株式会社HRBrainでは、Power to the peopleを合言葉に多種多様な人事課題を解決するプロダクトを開発・運営しています。
日本の労働環境を良くしてやるぜ！みんなが元気に活躍できる社会にしてやるぜ！
そんな熱い気持ちを持った方、一緒に働きませんか？
皆様のご応募をお待ちしております！

https://www.hrbrain.co.jp/recruit