「百聞は一見にしかず」。
複雑なシステムの仕組みや業務フローなどを説明する際、文字だけの文章よりも直感的な「図解」が添えられている方が圧倒的に伝わりやすいですよね。しかし、いちいち画像作成ソフトを起動して図形を配置し、画像として書き出してWordPressやHugoにアップロードするのは非常に手間がかかります…。

そんな課題を解決してくれる非常に便利なツールが Mermaid.js（マーメイド） です！
このライブラリを使うと、Markdownファイル内にルールに沿ったテキストを書くだけで、ブラウザ側が自動的にきれいな図形（SVG等）を描画してくれます。

このチュートリアルテーマでは、記事ごとにFront Matterのスイッチ一つでMermaidを動的に有効化できるように専用のカスタマイズを施しています。

0. 準備：テーマ側の設定

Mermaidを使うには、まずテーマ側でライブラリを読み込む準備が必要です。
詳しい手順は 外部ライブラリを使いこなそう！ (Google Fonts, Mermaid, etc.) の「上級編」で解説しています。

やること:

  1. layouts/partials/mermaid.html を作成（JS読み込み用）。
  2. layouts/baseof.html からそれを呼び出す。
  3. layouts/_markup/render-codeblock-mermaid.html を作成（描画用フック）。
    (※旧バージョンでは _default/_markup/ でした)

これが完了していれば、あとは以下の手順で簡単に図が描けます！

1. 使い方

記事の先頭にある設定（Front Matter）に、一行追加するだけです。

+++
title = "記事のタイトル"
mermaid = true  # <--- これを追加！
+++

これだけで、その記事内でMermaidが動くようになります。
（使わない記事ではオフにしておくことで、無駄な読み込みを防いでいます）

2. 書き方とサンプル

Markdownのコードブロックで、言語指定に mermaid と書きます。

フローチャート (Flowchart)

{{< mermaid >}}
graph LR
    A[Start] --> B{Is it working?}
    B -- Yes --> C[Great!]
    B -- No --> D[Debug]
    D --> B
{{< /mermaid >}}

実際の表示:

graph LR A[Start] --> B{Is it working?} B -- Yes --> C[Great!] B -- No --> D[Debug] D --> B

シーケンス図 (Sequence Diagram)

{{< mermaid >}}
sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!
{{< /mermaid >}}

実際の表示:

sequenceDiagram Alice->>John: Hello John, how are you? John-->>Alice: Great! Alice-)John: See you later!

ガントチャート (Gantt Chart)

{{< mermaid >}}
gantt
    title サイト制作スケジュール
    dateFormat  YYYY-MM-DD
    section 設計
    要件定義           :a1, 2026-02-01, 3d
    デザイン           :after a1, 5d
    section 開発
    コーディング       :2026-02-10, 5d
    テスト             :2d
{{< /mermaid >}}

実際の表示:

gantt title サイト制作スケジュール dateFormat YYYY-MM-DD section 設計 要件定義 :a1, 2026-02-01, 3d デザイン :after a1, 5d section 開発 コーディング :2026-02-10, 5d テスト :2d

3. ダークモード対応（CSSによる調整）

Mermaidで描画される図は、デフォルトでは「ライトモード」向けの配色になっているため、サイトをダークモードに切り替えた際に文字や線が見えづらくなることがあります。

これを簡単に解決するためのCSS設定（例）をご紹介します。
テーマのスタイルシート（assets/scss/style.scss など）に以下を追記してみてください。

/* ダークモード時のMermaid図の色合いを調整する */
[data-theme="dark"] .mermaid svg {
    /* 色を反転させて見やすくする */
    filter: invert(0.3); 
    
    /* もしくは以下のようにコントラストを調整するのもおすすめです */
    /* filter: contrast(0.5); */
}

設定する数値（0.3 や 0.5）はお好みのテイストに合わせて微調整してみてください。これだけで、ダークモード時にも図が自然になじむようになります。

Mermaidで効果的な図解を記事に取り入れよう

複雑な仕組みや手順を説明する際、文字だけでは伝わりにくい情報を「図解」として視覚的に表現することは、読者の理解度を深める上で非常に有効な手段です。
Mermaid.jsを使えばわざわざ別ツールで画像化する手間もなく、Markdown執筆のフローのままテキストベースでサクサクと図を描画でき、あとからの構成変更（修正）もテキストをいじるだけで済むので運用効率が飛躍的に向上します。積極的に技術記事などで活用してみましょう！🐠