PyCharmのMarkdownでmermaidのフロー図を書く【記法まとめとバージョンの罠】

構成図やフロー図はこれまで PlantUML で書いてきたのですが、リポジトリの README に置く図に関しては mermaid のほうが扱いやすい場面があります。テキストで書けるところは PlantUML と同じで、GitHub や GitLab がコードフェンスをそのまま図として描画してくれるため、レンダリング用のサーバーを別に用意しなくて済むからです。

この記事では、PyCharm の Markdown エディタで mermaid のフロー図を書く手順と記法をまとめます。あわせて、実際に手を動かして分かった「IDE が持つ mermaid のバージョンが固定されていて、新しい記法が通らない」という落とし穴についても記載します。

本記事の内容

1. PyCharmでmermaidを有効にする
- 1.1 チェックを入れても図が出ないとき
2. 最初の1枚を書いてみる
3. フローチャートの記法をまとめる
4. PyCharmが使うmermaidはバージョンが固定されている
- 4.1 手元のバージョンを調べる
5. PlantUMLとの使い分け
6. まとめ

1. PyCharmでmermaidを有効にする

mermaid の描画は PyCharm 本体ではなく、IDE が持っている mermaid.js が行います。既定では無効なので、まず有効化が必要です。

Ctrl+Alt+S で設定を開き、Languages & Frameworks の Markdown を選びます。2021 年前後のバージョンでは、ここに「Markdown Extensions」という一覧があり、その中の Mermaid にチェックを入れると有効になります。PlantUML も同じ一覧に並んでいます。

一方、新しいバージョンでは扱いが変わっています。JetBrains の公式ドキュメントでは、PlantUML は Markdown Extensions のまま、Mermaid は Plugins から導入する独立したプラグインとして案内されています。設定画面に Mermaid のチェックボックスが見当たらない場合は、プラグイン一覧のほうを探してください。

1.1 チェックを入れても図が出ないとき

有効化すると、PyCharm は mermaid.js をインターネットから取得してローカルに保存します。Windows であれば次の場所です。

# 実体はここに置かれる（製品名とバージョンは環境に合わせて読み替える）
dir "$env:LOCALAPPDATA\JetBrains\PyCharmCE2021.1\download-cache\mermaid\mermaid\mermaid.js"

このファイルが無ければ、取得そのものに失敗しています。社内プロキシ環境では、ここで詰まっていることが少なくありません。設定画面に項目自体が出てこないケースについては、以前に別記事にまとめています。

PycharmのMarkdown設定で拡張(PlantUML/Mermaid)が表示されない

2. 最初の1枚を書いてみる

.md ファイルを開き、コードフェンス（バッククォート3つ）の言語指定を mermaid にして、その中に図の定義を書きます。あとはエディタ右側のプレビューに図が表示されます。

graph TD
    A[障害の連絡を受ける] --> B{他の利用者も同じ症状か}
    B -->|はい| C[サーバー側を確認]
    B -->|いいえ| D[端末側を確認]
    C --> E[復旧作業]
    D --> E

1行目の graph に続く 2 文字が図の向きです。TD（上から下）のほかに TB BT LR（左から右）RL が使えます。フロー図が横に長くなりがちなときは LR にすると収まりがよくなります。

Markdown エディタ自体のセットアップは以下の記事にまとめています。画像の貼り付けや draw.io との連携もあわせて使うと、ドキュメント作成がかなり楽になります。

PyCharmで超快適なMarkdownエディタ環境を作る

3. フローチャートの記法をまとめる

よく使う記法を一覧にします。いずれも後述の環境（mermaid 8.9.1）で描画を確認したものです。

3.1 ノードの形

角括弧の種類でノードの形が決まります。判断は {}、データベースは [()]、というように使い分けると、それだけで図の意味が伝わります。

書き方	形	用途の例
`A[処理]`	四角	通常の処理
`A(受付)`	角丸の四角	開始・終了
`A([入力])`	両端が丸い四角	入出力
`A[[集計]]`	二重線の四角	サブルーチン・別フロー
`A[(台帳DB)]`	円柱	データベース
`A((開始))`	円	起点・合流点
`A{承認する}`	ひし形	条件分岐
`A{{通知}}`	六角形	イベント
`A[/入力用紙/]`	平行四辺形	帳票・手入力

ノードのラベルに丸括弧や記号を入れると構文解析に失敗することがあります。その場合は A["申請(部門長まで)"] のようにダブルクォートで囲みます。改行したいときはラベルの中に <br> を書きます。

3.2 線とラベル

書き方	見た目	用途の例
`A --> B`	実線の矢印	通常の遷移
`A --- B`	矢印なしの実線	単なる関連
`A -.-> B`	点線の矢印	非同期・任意の経路
`A ==> B`	太い矢印	主経路の強調
`A -- 承認 --> B`	ラベル付き	分岐条件
`A -.再送.-> B`	点線＋ラベル	例外時の経路

ラベルは A -->|承認| B のように矢印の後ろに縦棒で挟む書き方もできます。分岐の直後に条件を書きたいときはこちらのほうが読みやすくなります。

3.3 グループ化と色付け

subgraph で囲むと、ネットワークのセグメントや担当部署といった「まとまり」を表現できます。色は classDef でクラスを定義して class で当てるのが管理しやすい方法です。

flowchart LR
    subgraph office[社内LAN]
        PC[業務端末] --> PRX[プロキシ]
    end
    subgraph cloud[インターネット]
        SAAS[SaaS]
    end
    PRX --> SAAS
    PRX -.遮断.-> NG[許可外サイト]

    %% 注意を促したいノードだけ赤系にする
    classDef warn fill:#FDF2F2,stroke:#B91C1C,color:#B91C1C
    class NG warn

1つのノードだけを塗るなら style NG fill:#FDF2F2 と直接書くこともできます。線に色を付けたい場合は linkStyle 0 stroke:#B91C1C,stroke-width:2px のように、0 から数えた線の番号を指定します。

4. PyCharmが使うmermaidはバージョンが固定されている

ここが一番の落とし穴です。IDE は mermaid.js を毎回最新版に更新するわけではなく、プラグインに埋め込まれた固定のURLから取得します。手元の PyCharm Community 2021.1.3 では、その取得先が https://unpkg.com/mermaid@{version}/dist/mermaid.js という形で、{version} の部分がプラグイン側で決め打ちされていました。

実際に落ちてきたファイルを読み込んで動作を確認したところ、mermaid 8.9.1 でした。結果は次の通りです。

記法	8.9.1 での結果
`graph` / `flowchart` / `subgraph`	描画できる
`sequenceDiagram` / `classDiagram` / `stateDiagram-v2`	描画できる
`erDiagram` / `gantt` / `pie` / `journey` / `gitGraph`	描画できる
`classDef` / `style` / `linkStyle` / `click`	描画できる
`%%{init: ...}%%` によるテーマ指定	描画できる
`mindmap` / `timeline` / `quadrantChart` / `C4Context`	構文エラー
`requirementDiagram`	構文エラー
`subgraph` 内の `direction LR`	構文エラー
不可視のリンク `A ~~~ B`	構文エラー

つまり、Web の解説記事や mermaid.live で動いた記法が、そのまま PyCharm のプレビューで動くとは限りません。特に subgraph の中で向きを変える direction は解説記事でよく見かける書き方ですが、8.9.1 では通りませんでした。

4.1 手元のバージョンを調べる

一番早いのは、フェンスの中をわざと壊してプレビューを見る方法です。mermaid はエラー時に自分のバージョンを図として描画するため、次のような表示が出ます。

Syntax error in graph
mermaid version 8.9.1

新しい記法をどうしても使いたい場合は、そのバージョンの mermaid.js を上記の download-cache 配下に自分で置き換える手もあります。ただし IDE 側の想定と食い違う可能性があるため、通常は PyCharm では 8 系の範囲で書き、凝った図は GitHub 側の表示で確認すると割り切ったほうが安全です。

5. PlantUMLとの使い分け

両方を使ってみた感触としては、次のように分けるのが実用的でした。

	mermaid	PlantUML
得意なこと	README に置く簡単なフロー・シーケンス	詳細な構成図・UML 一式
描画される場所	GitHub / GitLab がそのまま表示する	別途サーバーや Java が必要
表現力	素朴。細かい制御は苦手	AWS アイコン等のライブラリが豊富
学習コスト	低い	中程度