🐥

Mermaid CLIをDockerで使う（Puppeteerエラー解決）

に公開
Docker
Mermaid
mmdc
tech

TL;DR

alias mmdc='docker run --rm -u $(id -u):$(id -g) -v $(pwd):/data minlag/mermaid-cli'

これで mmdc -i diagram.mmd -o diagram.png が動く。ホームディレクトリ汚さない。

問題: ただ図がほしいだけなのに

$ mmdc -i hoge.mmd -o huga.svg
Error: Could not find Chrome (ver. xxxx). This can occur if either
 1. you did not perform an installation before running the script (e.g. `npx puppeteer browsers install chrome-headless-shell`) or
 2. your cache path is incorrectly configured (which is: /home/わし/.cache/puppeteer).
For (2), check out our guide on configuring puppeteer at https://pptr.dev/guides/configuration.

こんなの言われたのでnpx puppeteer browsers install chrome-headless-shellをしてみても、動かない。そもそもインストール先パス通ってない。仕組みがよくわからない。

別に興味もなくて、ただ、mermaidから図がほしいだけなのになぜ毎回こんな思いをせねばならぬのだ。

パワー解決: Dockerコンテナで完結させる

公式がDocker imageを提供してるので、それ使う。

基本の使い方

docker run --rm -v $(pwd):/data minlag/mermaid-cli -i input.mmd -o output.png

エイリアス化

毎回打つのダルいので .bashrc or .zshrc に追記:

alias mmdc='docker run --rm -u $(id -u):$(id -g) -v $(pwd):/data minlag/mermaid-cli'

-u $(id -u):$(id -g) を入れることで、生成されるファイルの所有者が自分になる（rootにならない）。

使用例

# Mermaid記法で図を書く
cat > diagram.mmd << 'EOF'
graph TB
    A[ユーザー] --> B{判定}
    B -->|Yes| C[処理A]
    B -->|No| D[処理B]
EOF

# PNG生成
mmdc -i diagram.mmd -o diagram.png

# SVG生成
mmdc -i diagram.mmd -o diagram.svg

# PDF生成
mmdc -i diagram.mmd -o diagram.pdf

ハマりポイント1: 権限エラー

-u $(id -u):$(id -g) を忘れると以下のエラーが出る:

Error: EACCES: permission denied, open 'diagram.svg'

生成されたファイルがroot所有になるため。

対処

エイリアスに -u $(id -u):$(id -g) を必ず含める。

既にroot所有のファイルができてしまった場合:

sudo chown $(id -u):$(id -g) *.svg

ハマりポイント2: SVGが透過背景

SVGは背景が透過なので、ダークテーマのエディタ/ブラウザで開くと文字が見えないことがある。

対処1: PNGで出力（推奨）

mmdc -i diagram.mmd -o diagram.png

対処2: SVGに背景色を埋め込む

mmdc -i diagram.mmd -o diagram.svg -b white

どっち使うべき?

  • PNG: ブログ/ドキュメント埋め込み用（互換性高い）
  • SVG: 拡大縮小が必要な場合（ベクター形式）

メリット

  • ホームディレクトリ汚れない
  • グローバルnpmパッケージ不要
  • Chrome/Chromiumのインストール不要
  • バージョン管理が楽（imageのtagで固定できる）

デメリット

  • 初回実行時にDocker imageのpull
    • minlag/mermaid-cliは約2GBある（Chrome含むため）。
  • 実行が若干遅い（コンテナ起動のオーバーヘッド）
    • 体感では1-2秒程度のラグ

トレードオフ

  • Docker版: ホームディレクトリ汚さない、2GB消費
  • npm版: ~/.cache/puppeteerに200MB、グローバル汚染
  • オンライン: https://mermaid.live/ 使えばディスク0MB

参考

Discussion