NotionでMermaidを書くテクニック

はじめに

NotionのページではMermaidをコードブロックとして記述でき、フローチャートやシーケンス図、構成図などをページ内にそのまま埋め込めます。

本記事では、Notion上でMermaidを扱う際に押さえておきたいポイントやテクニックを、いくつかピックアップして紹介します。

基本的な使い方

Mermaid自体の使い方は下記の公式ドキュメントや、解説記事を参照してください。

また、NotionでもMermaid Master Guideが公開されていますので、よければ参照してください。

Mermaidの記載

コードブロックの追加

NotionのページでMermaidを書くには、Mermaidのコードブロックを使用します。

MermaidのコードブロックはスラッシュコマンドでMermaidを指定する方法や

直接コードブロックを追加し、言語選択でMermaidを指定する方法などがあります。

コードブロックの表示領域

NotionのMermaidのコードブロックの初期表示では、Mermaid記法を記述するコード記述領域と、記述した内容を図として表示するプレビュー領域の両方が分割して表示されています。

コード記述領域にMermaid記法を記述することで、プレビュー領域に記述した内容が図として表示されます。

表示方法を変更したい場合は、Mermaidのコードブロックの右上の表示方法変更ボタンから、コード記述領域のみ表示、プレビュー領域のみ表示、分割表示のいずれかに変更することができます。

Mermaidの設定

設定の記述方法

Mermaidでは図毎に個別の設定を行うことができますが、NotionでもMermaidのコードブロック毎に設定を行うことができます。

また、設定を行うにはコードブロックの先頭にinitディレクティブ(JSON形式)を記述します。

mermaid

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#00ff00'
  }
}}%%
graph TD
  Mermaid --> Diagram

Frontmatter(YAML形式)を使用した設定方法は有効に機能しない場合があるので、注意してください。

mermaid

---
title: Hello Title
config:
  theme: base
  themeVariables:
    primaryColor: "#00ff00"
---
graph TD
  Mermaid --> Diagram

テーマの指定方法

Mermaidではテーマを指定しない場合、通常はdefaultが適用されますが、Notionではneutralが適用されます。

テーマを変更したい場合は、initディレクティブ(JSON形式)のthemeに、任意のテーマを指定してください。

テーマ	default	neutral	dark	forest	base
イメージ

図の表示

拡大表示機能

Mermaidのコードブロックのプレビュー領域では図をSVGとして表示していますが、Notionを表示しているウィンドウの横幅を縮めた場合に、図も縮小されて表示されます。

図が縮小されすぎて見づらい場合は、プレビュー領域をクリックすると図が拡大表示されます。

また、拡大表示されている図を右クリックして画像をコピーすると、図がクリップボードに保存され、エディタなどに貼り付けることができます。

Mermaidで表示した図はテキスト検索やテキスト選択が可能ですが、Notionのプレビュー領域の図や拡大表示中の図ではテキスト操作に対応していないので注意してください。

外部画像の指定機能

Mermaidではノードに外部の画像を指定することができますが、Notionでも同様に画像を指定することができます。

mermaid

flowchart LR
  N1@{ img: "https://api.iconify.design/ic:baseline-laptop-chromebook.svg", w: 60, h: 60, constraint: "on" }

  subgraph GC[AWS Cloud]
    N2@{ img: "https://api.iconify.design/logos/aws-elb.svg", label: "ELB", pos: "t", w: 60, h: 60, constraint: "on" }
    N3@{ img: "https://api.iconify.design/logos/aws-ecs.svg", label: "ECS", pos: "t", w: 60, h: 60, constraint: "on" }
    N4@{ img: "https://api.iconify.design/logos/aws-iam.svg", label: "IAM", pos: "t", w: 60, h: 60, constraint: "on" }
  end

  N1 --> N2 --> N3 ~~~ N4

  style N1 fill:none,stroke:none
  style GC fill:none,color:#345,stroke:#345

背景が透過された画像を使用する場合は、ノードのスタイルの背景と枠線をnoneに設定すると、綺麗に透過されます。

また、Mermaidで画像を指定する方法は下記を参照してください。

ノードのクリック機能

Mermaidのコードブロックのプレビュー領域のみですが、ノードに設定したclickディレクティブが使用できます。
(拡大表示中の図には対応していません)

プレビュー領域の対象ノードにマウスを合わせるとカーソルがハンドカーソルに変更し、クリックすると指定したURLに遷移できます。

mermaid

graph TD
  Mermaid --> Diagram
  click Mermaid href "https://qiita.com/" _blank

MermaidではsecurityLevelがstrict相当だと、clickが動作しない場合があります。

Notion側の実装やアップデートにより挙動が変わる可能性があるため、期待どおりに動かない場合はNotion側の仕様変更も疑ってください。(参考)

Notion用テクニック

Mermaidを並列配置する

他のMermaidを扱っているサービスではあまり見ない機能ですが、Notionのページでは、Mermaidのコードブロックを並列に配置することができます。

例えば変更前後のMermaidのコードブロックを並列に配置させ、変化をわかりやすく表現することができます。

ただし、横に長い図は自動縮小で小さく表示されやすいため、この使い方は難しい場合があります。一方で、縦に長いシンプルな図であれば視認性を保ちやすく、比較用途などで非常に便利な機能です。

レイアウトを昔に戻す

2025年のNotionのアップデートでMermaidのlayoutがelkになり、ノード間の線が丸みを帯びなくなり、線が複数ある場合は見やすくなりました。

その反面、線の回り込みが発生し、ノードが中央に配置されなくなる、シンプルなflowchartだと線が角ついて見づらくなる、などの問題が発生するようになりました。

そのような場合は、Mermaidの設定のlayoutにdagreを指定することで、元のレイアウトに戻すことができます。

mermaid

%%{init: {'layout': 'dagre'}}%%
graph TD
  Mermaid --> Diagram1
  Mermaid --> Diagram2

layoutは何を指定してもdagreにリセットされる(?)ような動きを見せます。

また、flowchartのdefaultRendererの指定は機能していないようなので、注意してください。

縦長に書く

前述のとおり、Notionでは表示中のウィンドウ幅に合わせて図が自動的に縮小されます。

横方向に広がる図ほど縮小率が大きくなるため、結果として文字やノードが小さく見えがちなので、可能な範囲で図を縦方向に展開するよう記述すると、縮小をある程度抑えられます。

たとえばシンプルなflowchartであれば、向きをTD(上→下)やBT(下→上)に指定し、ノードを縦に並べることで、横幅の消費を抑えられ、見やすさを保ちやすくなります。

また、AWS構成図など複雑な図については、レイアウトの考え方や記載のコツを別記事にまとめているので、よければ参考にしてください。

余白を縮小する

Notionのページには左右の余白を縮小する機能があり、有効にするとMermaidのコードブロックを含むコンテンツの横幅を少し広げられます。

横幅に余裕ができると図の縮小も抑えやすくなるため、特に支障がなければ余白の縮小設定を有効にすることをおすすめします。

ノード間の間隔を調整する

Mermaidのlayout設定でdagreを指定した場合、flowchartのノードの間隔を調整できるようになります。

nodeSpacingは同じ階層のノード間隔、rankSpacingは異なる階層とのノード間隔をそれぞれ指定することができます。

また、それぞれの間隔を小さくすると図を間延びさせずにコンパクトにでき、横幅にも余裕ができるため、図の縮小も抑えやすくなります。

mermaid

%%{init:{'layout': 'dagre','flowchart':{'nodeSpacing':20,'rankSpacing':20}}}%%
flowchart TD
  Mermaid --> Diagram1 --> Diagram1-1 --> Diagram1-2
  Mermaid --> Diagram2 --> Diagram2-1 --> Diagram2-2
  Mermaid --> Diagram3 --> Diagram3-1 --> Diagram3-2
  Mermaid --> Diagram4 --> Diagram4-1 --> Diagram4-2

ノード間隔を小さくした際に、ノード間の線の矢印が不自然に見えることがありますが、曲線の描画方法を変更すると自然に見えるようになる場合があります。

例えば縦方向の矢印が不自然な場合はcurveにmonotoneYを指定し、

mermaid

%%{init:{'layout': 'dagre','flowchart':{'nodeSpacing':20,'rankSpacing':20,'curve': 'monotoneY'}}}%%
flowchart TD
  Mermaid --> Diagram1 --> Diagram1-1 --> Diagram1-2
  Mermaid --> Diagram2 --> Diagram2-1 --> Diagram2-2
  Mermaid --> Diagram3 --> Diagram3-1 --> Diagram3-2
  Mermaid --> Diagram4 --> Diagram4-1 --> Diagram4-2

横方向の矢印が不自然な場合はcurveにmonotoneXを指定すると、自然に見える場合があります。

mermaid

%%{init:{'layout': 'dagre','flowchart':{'nodeSpacing':20,'rankSpacing':20,'curve': 'monotoneX'}}}%%
flowchart LR
  Mermaid --> Diagram1 --> Diagram1-1 --> Diagram1-2
  Mermaid --> Diagram2 --> Diagram2-1 --> Diagram2-2
  Mermaid --> Diagram3 --> Diagram3-1 --> Diagram3-2
  Mermaid --> Diagram4 --> Diagram4-1 --> Diagram4-2

他にもいくつかcurveに指定できるパラメータがあるので、試したい場合は公式ドキュメントをご確認ください。

Notion AIを使う

Notion AIが使用できるプランに加入している場合は、Notion AIにMermaidの図を書かせることができます。

Notion AIに依頼をするには、任意のNotionページの場所でスペースを押してNotion AIを呼び出す方法や

スラッシュコマンドでAIブロックを追加する方法などがあります。

上記のサンプルではWebでも公開されているNotionの歴史をMermaidで記載してもらいましたが、Notion AIではNotionに蓄積された情報を使用してMermaidの図を書かせることができます。

特に、社内ナレッジをNotionに集約している環境では強力なツールとして活用できるため、できる限り情報をNotionに集約しておくと効果的です。

おわりに

NotionのMermaidはページ内で完結する図として扱えるだけでなく、並列配置や拡大表示などNotionの編集体験と組み合わせることで、ドキュメントの可読性を大きく高められます。

また、画像データではなく、MermaidとしてNotionに記載することでNotion AIが認識しやすい情報として蓄積され、よりNotion AIが強力なツールとなっていきます。

本記事が、Notionの運用改善に少しでも役立てば幸いです。