T-CREATOR

Mermaid CLI（mmdc）速攻導入：インストールからバッチ生成・自動リサイズまで

Mermaid CLI（mmdc）速攻導入：インストールからバッチ生成・自動リサイズまで

Mermaid の図を Markdown で書くのは便利ですが、画像ファイルとして保存したいときに困ったことはありませんか？ 資料作成やドキュメント生成で、複数の Mermaid 図を一括で画像化したい場面は意外と多いものです。

本記事では、Mermaid CLI（mmdc）を使って、コマンドライン上で Mermaid 図を画像に変換する方法を、インストールから実践的なバッチ処理、自動リサイズまで段階的に解説します。 初めての方でも迷わず導入できるよう、エラー対処法も含めて丁寧にご紹介しますね。

背景

Mermaid とは

Mermaid は、テキストベースで図を作成できる JavaScript ライブラリです。 フローチャート、シーケンス図、クラス図など、さまざまなダイアグラムをシンプルな記法で記述できます。

GitHub や Notion など、多くのプラットフォームが Mermaid をサポートしており、開発者の間で広く使われています。

Web ブラウザでの利用から CLI への移行

従来、Mermaid 図を画像化するには、Mermaid Live Editorなどの Web ツールを使う必要がありました。 しかし、図が増えてくると、一つひとつ手作業で保存するのは非効率ですよね。

自動化や CI/CD パイプラインへの組み込みを考えると、コマンドラインツールが欠かせません。

図の意図：Mermaid 利用の変遷を時系列で示します。

mermaidflowchart LR
  A["手動での図作成"] -->|"Web Editor使用"| B["個別に画像保存"]
  B -->|"複数ファイル管理が煩雑"| C["CLI導入の必要性"]
  C -->|"mmdc導入"| D["自動化・バッチ処理"]
  D -->|"効率化"| E["継続的な図の管理"]

この図から分かるように、手動管理から CLI ツールへの移行により、作業の自動化と効率化が実現できます。

Mermaid CLI の役割

Mermaid CLI（mmdc）は、Mermaid 図をコマンドラインから画像や PDF、SVG に変換できるツールです。 Node.js ベースで動作し、Puppeteer や Playwright を使ってブラウザレンダリングを行います。

これにより、スクリプトやビルドプロセスに組み込んで、図の生成を自動化できるようになります。

課題

手動での画像生成の限界

Web Editor を使った手動での画像保存には、以下のような課題があります。

#課題影響
1図が多いと時間がかかる生産性の低下
2更新のたびに再保存が必要運用負荷の増加
3バージョン管理が難しい整合性の欠如
4チーム間での共有が煩雑コラボレーションの阻害

ドキュメントに 10 個、20 個と図が増えていくと、メンテナンスが大変になってしまいます。

複数ファイルの一括処理

プロジェクトで複数の Mermaid ファイルを管理する場合、一つずつ手動で処理するのは現実的ではありません。 新しい図を追加したり、既存の図を更新したりするたびに、全ての図を再生成する必要があります。

特に、ドキュメント生成パイプラインや CI/CD での自動化を考えると、バッチ処理機能が必須です。

サイズと解像度の調整

生成される画像のサイズや解像度を細かく制御したい場合、Web Editor では限界があります。 資料の用途に応じて、高解像度の PNG、軽量な SVG、印刷用の PDF など、出力形式を使い分けたいですよね。

また、図の幅や高さを統一したり、レティナディスプレイ対応の高 DPI 画像を生成したりする必要もあります。

図の意図：手動処理と自動処理の作業量を比較します。

mermaidflowchart TB
  subgraph manual["手動処理"]
    M1["Mermaidファイル"] --> M2["Web Editorで開く"]
    M2 --> M3["画像として保存"]
    M3 --> M4["サイズ調整"]
    M4 --> M5["ファイル名変更"]
    M5 --> M6["適切な場所に配置"]
  end

  subgraph auto["CLI自動処理"]
    A1["Mermaidファイル"] --> A2["スクリプト実行"]
    A2 --> A3["一括変換完了"]
  end

  manual -.->|時間がかかる| comparison["作業効率"]
  auto -.->|瞬時に完了| comparison

この図から、CLI を使った自動処理がいかに効率的かが理解できます。

解決策

Mermaid CLI（mmdc）の導入

Mermaid CLI は、これらの課題を一気に解決してくれるツールです。 コマンド一つで、Mermaid ファイルを画像に変換し、サイズ調整やバッチ処理も簡単に実現できます。

主な機能は以下の通りです。

#機能説明
1画像形式変換PNG、SVG、PDF 形式に対応
2バッチ処理複数ファイルの一括変換
3サイズ指定幅・高さ・背景色のカスタマイズ
4テーマ設定ダーク・ライトテーマの切り替え
5設定ファイル対応JSON 形式での詳細設定

システム要件

Mermaid CLI を使用するには、以下の環境が必要です。

  • Node.js（バージョン 14 以降を推奨）
  • npm または Yarn
  • Chromium または Chrome（Puppeteer が自動インストール）

すでに Node.js 環境があれば、すぐに始められます。

図の意図：Mermaid CLI の処理フローを示します。

mermaidflowchart LR
  input["Mermaid<br/>ファイル(.mmd)"] --> mmdc["mmdc<br/>コマンド"]
  mmdc --> puppeteer["Puppeteer/<br/>Playwright"]
  puppeteer --> render["ブラウザ<br/>レンダリング"]
  render --> output["画像ファイル<br/>(PNG/SVG/PDF)"]

  config["設定ファイル<br/>(省略可)"] -.->|"テーマ・サイズ等"| mmdc

この処理フローにより、テキストファイルから高品質な画像が生成されます。

具体例

インストール手順

npm を使用したインストール

最も簡単な方法は、npm でグローバルインストールすることです。

bashnpm install -g @mermaid-js/mermaid-cli

このコマンドで、システム全体からmmdcコマンドが使えるようになります。

インストール後、バージョンを確認して正しくインストールされたか確認しましょう。

bashmmdc --version

正常にインストールされていれば、バージョン番号（例：10.6.1）が表示されます。

Yarn を使用したインストール

Yarn を使っている場合は、以下のコマンドでインストールできます。

bashyarn global add @mermaid-js/mermaid-cli

Yarn のグローバルパスが通っていることを確認してください。

bashyarn global bin

このコマンドで表示されるパスが、環境変数PATHに含まれている必要があります。

プロジェクト単位でのインストール

特定のプロジェクトでのみ使用する場合は、ローカルインストールも可能です。

bashcd your-project
yarn add -D @mermaid-js/mermaid-cli

ローカルインストールした場合、package.jsonの scripts に登録して使います。

json{
  "scripts": {
    "mermaid": "mmdc"
  }
}

これでyarn mermaid -i input.mmd -o output.pngのように実行できます。

インストール時のエラー対処

エラーコード：EACCES: permission denied

インストール時に権限エラーが発生する場合があります。

swiftError: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@mermaid-js'

発生条件： グローバルインストール時に、Node.js のインストールディレクトリへの書き込み権限がない場合に発生します。

解決方法：

  1. sudo を使用する（非推奨）
bashsudo npm install -g @mermaid-js/mermaid-cli
  1. npm のグローバルディレクトリを変更する（推奨）
bashmkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
  1. nodebrew や nvm を使用して Node.js を再インストールする

これにより、ユーザー権限で Node.js と npm パッケージを管理できるようになります。

エラーコード：Chromium revision is not downloaded

Puppeteer のインストール時に Chromium のダウンロードに失敗することがあります。

vbnetError: Chromium revision is not downloaded. Run "npm install" or "yarn install"

発生条件： ネットワーク制限や、企業のプロキシ環境下で Chromium のダウンロードがブロックされる場合に発生します。

解決方法：

  1. 環境変数でプロキシを設定する
bashexport HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
npm install -g @mermaid-js/mermaid-cli
  1. システムの Chromium を使用する設定にする
bashexport PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
npm install -g @mermaid-js/mermaid-cli

この場合、別途 Chromium をインストールし、パスを指定する必要があります。

基本的な使い方

単一ファイルの変換

まず、簡単な Mermaid ファイルを作成しましょう。

sample.mmdという名前でファイルを作成します。

cssflowchart LR
  A["開始"] --> B["処理"]
  B --> C["終了"]

このファイルを PNG 画像に変換します。

bashmmdc -i sample.mmd -o sample.png

実行すると、sample.pngが生成されます。

出力形式の指定

出力形式は、ファイル拡張子またはオプションで指定できます。

SVG 形式で出力

bashmmdc -i sample.mmd -o sample.svg

SVG 形式は、ベクター画像なので拡大しても劣化しません。

PDF 形式で出力

bashmmdc -i sample.mmd -o sample.pdf

PDF 形式は、印刷用資料や正式なドキュメントに適しています。

背景色の指定

デフォルトでは背景が透明ですが、背景色を指定することもできます。

白い背景を設定

bashmmdc -i sample.mmd -o sample.png -b white

カスタム背景色を設定

bashmmdc -i sample.mmd -o sample.png -b '#f0f0f0'

16 進数のカラーコードを使って、任意の背景色を指定できます。

バッチ処理の実装

単純なループ処理

複数の Mermaid ファイルを一括変換するには、シェルスクリプトを使います。

Bash スクリプト例

convert-all.shというファイルを作成します。

bash#!/bin/bash

# mmdファイルが格納されているディレクトリ
INPUT_DIR="./diagrams"
# 出力先ディレクトリ
OUTPUT_DIR="./images"

次に、出力ディレクトリを作成し、各ファイルを処理します。

bash# 出力ディレクトリがなければ作成
mkdir -p "$OUTPUT_DIR"

# すべての.mmdファイルを処理
for file in "$INPUT_DIR"/*.mmd; do
  # ファイル名（拡張子なし）を取得
  filename=$(basename "$file" .mmd)

  echo "Converting: $filename"

  # PNG形式で変換
  mmdc -i "$file" -o "$OUTPUT_DIR/$filename.png"
done

echo "All files converted!"

スクリプトに実行権限を付与して実行します。

bashchmod +x convert-all.sh
./convert-all.sh

これで、diagramsフォルダ内のすべての.mmdファイルが、imagesフォルダに PNG 画像として保存されます。

エラーハンドリング付きスクリプト

実用的なスクリプトには、エラー処理を追加しましょう。

bash#!/bin/bash

INPUT_DIR="./diagrams"
OUTPUT_DIR="./images"
LOG_FILE="./conversion.log"

# ログファイルを初期化
echo "Conversion started at $(date)" > "$LOG_FILE"

各ファイルの変換時にエラーチェックを行います。

bash# カウンター初期化
success_count=0
error_count=0

for file in "$INPUT_DIR"/*.mmd; do
  filename=$(basename "$file" .mmd)

  echo "Processing: $filename" | tee -a "$LOG_FILE"

  # mmdc実行
  if mmdc -i "$file" -o "$OUTPUT_DIR/$filename.png" 2>> "$LOG_FILE"; then
    echo "✓ Success: $filename" | tee -a "$LOG_FILE"
    ((success_count++))
  else
    echo "✗ Error: $filename" | tee -a "$LOG_FILE"
    ((error_count++))
  fi
done

最後に、結果のサマリーを表示します。

bashecho "---" | tee -a "$LOG_FILE"
echo "Conversion completed at $(date)" | tee -a "$LOG_FILE"
echo "Success: $success_count files" | tee -a "$LOG_FILE"
echo "Errors: $error_count files" | tee -a "$LOG_FILE"

このスクリプトにより、どのファイルの変換に失敗したか一目で分かります。

package.json を使った管理

Node.js プロジェクトでは、package.jsonの scripts でバッチ処理を管理できます。

json{
  "scripts": {
    "diagram:build": "node scripts/convert-diagrams.js",
    "diagram:watch": "nodemon --watch diagrams --exec 'yarn diagram:build'"
  }
}

scripts​/​convert-diagrams.jsファイルを作成します。

javascriptconst { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

const INPUT_DIR = './diagrams';
const OUTPUT_DIR = './images';

ディレクトリを読み込み、各ファイルを変換します。

javascript// 出力ディレクトリを作成
if (!fs.existsSync(OUTPUT_DIR)) {
  fs.mkdirSync(OUTPUT_DIR, { recursive: true });
}

// mmdファイルを取得
const files = fs
  .readdirSync(INPUT_DIR)
  .filter((file) => file.endsWith('.mmd'));

console.log(`Found ${files.length} diagram files`);

各ファイルに対して変換を実行します。

javascriptfiles.forEach((file, index) => {
  const inputPath = path.join(INPUT_DIR, file);
  const outputPath = path.join(
    OUTPUT_DIR,
    file.replace('.mmd', '.png')
  );

  try {
    console.log(
      `[${index + 1}/${files.length}] Converting ${file}...`
    );
    execSync(`mmdc -i "${inputPath}" -o "${outputPath}"`, {
      stdio: 'inherit',
    });
  } catch (error) {
    console.error(
      `Failed to convert ${file}:`,
      error.message
    );
  }
});

console.log('Conversion completed!');

これでyarn diagram:buildコマンドで一括変換できます。

自動リサイズ機能

幅と高さの指定

画像のサイズを統一したい場合、幅や高さを指定できます。

幅を指定

bashmmdc -i sample.mmd -o sample.png -w 800

幅を 800 ピクセルに固定し、高さは自動調整されます。

高さを指定

bashmmdc -i sample.mmd -o sample.png -H 600

高さを 600 ピクセルに固定します。

幅と高さを両方指定

bashmmdc -i sample.mmd -o sample.png -w 800 -H 600

ただし、アスペクト比が変わるため、図が歪む可能性があります。

スケール指定

解像度を上げたい場合は、スケールオプションを使います。

bashmmdc -i sample.mmd -o sample.png -s 2

スケール 2 を指定すると、元のサイズの 2 倍の解像度で生成されます。 レティナディスプレイ対応の高解像度画像が必要な場合に有効です。

設定ファイルでの一括管理

毎回オプションを指定するのは面倒なので、設定ファイルを使いましょう。

puppeteer-config.jsonを作成します。

json{
  "args": ["--no-sandbox", "--disable-setuid-sandbox"],
  "headless": true,
  "timeout": 60000
}

この設定ファイルを使って変換します。

bashmmdc -i sample.mmd -o sample.png -p puppeteer-config.json

より詳細な設定も可能です。

json{
  "args": ["--no-sandbox"],
  "headless": true,
  "timeout": 60000,
  "viewport": {
    "width": 1920,
    "height": 1080,
    "deviceScaleFactor": 2
  }
}

deviceScaleFactorを 2 に設定することで、高解像度出力が可能になります。

テーマ設定

Mermaid のテーマを指定して、見た目を変更できます。

デフォルトテーマ

bashmmdc -i sample.mmd -o sample.png -t default

ダークテーマ

bashmmdc -i sample.mmd -o sample.png -t dark

フォレストテーマ

bashmmdc -i sample.mmd -o sample.png -t forest

ニュートラルテーマ

bashmmdc -i sample.mmd -o sample.png -t neutral

資料の雰囲気に合わせてテーマを選択できます。

CSS 設定ファイルの活用

さらにカスタマイズしたい場合、CSS 設定ファイルを使います。

custom-style.cssを作成します。

css.node rect {
  fill: #e3f2fd;
  stroke: #1976d2;
  stroke-width: 2px;
}

.node text {
  font-family: 'Hiragino Sans', 'Yu Gothic', sans-serif;
  font-size: 14px;
}

エッジ（矢印）のスタイルも変更できます。

css.edgePath .path {
  stroke: #1976d2;
  stroke-width: 2px;
}

.edgeLabel {
  background-color: #ffffff;
  padding: 4px;
  border-radius: 4px;
}

この CSS ファイルを適用して変換します。

bashmmdc -i sample.mmd -o sample.png -C custom-style.css

独自のスタイルを適用した図を生成できます。

高度なバッチスクリプト例

複数の出力形式とサイズバリエーションを一度に生成するスクリプトを作成しましょう。

bash#!/bin/bash

INPUT_FILE="$1"
BASENAME=$(basename "$INPUT_FILE" .mmd)
OUTPUT_DIR="./output"

# 出力ディレクトリ作成
mkdir -p "$OUTPUT_DIR"/{png,svg,pdf}/{small,medium,large}

各サイズと形式の組み合わせで変換します。

bashecho "Generating images for: $BASENAME"

# PNG形式（3サイズ）
mmdc -i "$INPUT_FILE" -o "$OUTPUT_DIR/png/small/$BASENAME.png" -w 400
mmdc -i "$INPUT_FILE" -o "$OUTPUT_DIR/png/medium/$BASENAME.png" -w 800
mmdc -i "$INPUT_FILE" -o "$OUTPUT_DIR/png/large/$BASENAME.png" -w 1200 -s 2

# SVG形式
mmdc -i "$INPUT_FILE" -o "$OUTPUT_DIR/svg/$BASENAME.svg"

# PDF形式
mmdc -i "$INPUT_FILE" -o "$OUTPUT_DIR/pdf/$BASENAME.pdf"

完了メッセージを表示します。

bashecho "✓ Generated all variations for $BASENAME"
ls -lh "$OUTPUT_DIR"/**/*"$BASENAME"*

このスクリプトを実行すると、一つの Mermaid ファイルから複数の形式とサイズのバリエーションが生成されます。

bash./generate-all.sh diagrams/my-flowchart.mmd

CI/CD パイプラインへの組み込みも簡単です。

GitHub Actions での自動化例

最後に、GitHub Actions での自動変換例をご紹介します。

.github​/​workflows​/​mermaid.ymlを作成します。

yamlname: Generate Mermaid Diagrams

on:
  push:
    paths:
      - 'diagrams/**/*.mmd'
  pull_request:
    paths:
      - 'diagrams/**/*.mmd'

ジョブの設定を行います。

yamljobs:
  generate:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

Mermaid CLI をインストールして実行します。

yaml- name: Install Mermaid CLI
  run: yarn global add @mermaid-js/mermaid-cli

- name: Convert diagrams
  run: |
    mkdir -p images
    for file in diagrams/*.mmd; do
      filename=$(basename "$file" .mmd)
      mmdc -i "$file" -o "images/$filename.png" -b white
    done

生成された画像をコミットします。

yaml- name: Commit generated images
  run: |
    git config --local user.email "action@github.com"
    git config --local user.name "GitHub Action"
    git add images/
    git diff --quiet && git diff --staged --quiet || \
      git commit -m "Update generated diagrams"
    git push

これで、Mermaid ファイルを更新するたびに、自動的に画像が生成されてリポジトリにコミットされます。

図の意図：自動化されたワークフローを示します。

mermaidsequenceDiagram
  participant Dev as 開発者
  participant GH as GitHub
  participant Action as GitHub Actions
  participant Repo as リポジトリ

  Dev->>GH: .mmdファイルをpush
  GH->>Action: ワークフロー起動
  Action->>Action: mmdc実行
  Action->>Action: 画像生成
  Action->>Repo: 画像をコミット
  Repo->>Dev: 更新完了通知

このフローにより、開発者は Mermaid ファイルを編集するだけで、画像生成が自動的に行われます。

まとめ

Mermaid CLI（mmdc）を導入することで、Mermaid 図の管理が劇的に効率化されます。 本記事では、インストールからバッチ処理、自動リサイズまで、実践的な使い方を段階的にご紹介しました。

重要なポイントを振り返りましょう。

#ポイント効果
1npm または Yarn で簡単インストールすぐに始められる
2コマンド一つで画像変換手作業から解放される
3シェルスクリプトでバッチ処理複数ファイルを一括管理
4サイズ・テーマのカスタマイズ用途に応じた出力が可能
5CI/CD パイプラインへの組み込み完全自動化を実現

特に、バッチ処理と CI/CD 連携により、ドキュメント管理の負担が大幅に軽減されます。 図の更新漏れや形式の不統一といった問題も解消できるでしょう。

Mermaid CLI は、技術ドキュメントやプロジェクト資料を扱う開発者にとって、必須のツールと言えますね。 ぜひ、今日から導入して、ドキュメント作成の効率化を実感してください。

プロジェクトの規模が大きくなるほど、その恩恵は大きくなります。 最初の設定に少し時間をかけるだけで、長期的には大きな時間節約になるでしょう。

関連リンク

Mermaidの記事Mermaid

もっと見る

記事Article

もっと見る

ブログBlog

もっと見る

書籍レビューReview

もっと見る