はじめに
ワークフローをMermaidで書いたmarkdownのドキュメントを作成しているときに、VSCode Markdown PDFを使ってpdf化していたら謎の空白ページが発生して躓いたので個人的な備忘録として残します。
前提条件
VSCode設定の必須項目
Mermaid図をPDF化するには、Chromiumベースのブラウザのパスを指定する必要がある。指定しないとMermaid図がコードブロックのまま出力される。
例:
settings.json に追加:
{
"markdown-pdf.executablePath": "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe"
}
設定後:
今回私が使っていたのがEdgeなので上記の設定ですが、Chromeまたは他のChromiumブラウザ使っている人は各々のインストールパスに合わせてください。
※ パスの区切り文字は\\（バックスラッシュ2つ）でエスケープが必要なので注意
問題
Visual Studio Codeの拡張機能であるMarkdown PDFでMermaid図を含むMarkdownをPDF化する際、以下の問題が発生：
空白ページの問題: Mermaid図の前に不要な空白ページが生成される
- 初期状態では空白ページがMermaid図のデフォルト背景色で埋まっていた
- 原因：Mermaid図がページサイズを超えて大きく、次のページに配置されていた
成功した解決策
custom.cssでページサイズに収める
/* Mermaid図のサイズをA4ページに収める */
.mermaid {
max-width: 180mm; /* A4幅210mm - 左右余白30mm */
max-height: 250mm; /* A4高さ297mm - 上下余白47mm */
margin: 0 auto;
}
.mermaid svg {
max-width: 100%;
max-height: 250mm;
height: auto;
}
-
結果：mermaidにおける図がページをまたぐと発生するようなので図がページサイズ（A4）に収まるようにすると解消
試行錯誤の記録（失敗集）
試行1: 背景色を透明化
custom.cssで.mermaid { background-color: transparent !important; }を設定
.mermaid {
background-color: transparent !important;
}
- ❌ 結果：空白ページの背景色が透明になっただけで未解決
試行2: 改ページ制御
.mermaid {
page-break-before: avoid !important;
page-break-after: avoid !important;
page-break-inside: avoid !important;
}
- ❌ 結果：逆に空白ページが増えた
試行3: 高さ制限のみ
.mermaid {
max-height: 250mm;
}
- ❌ 結果：表示範囲が小さくなるだけで図のサイズが変わらないので見切れる
試行4: スケーリング
.mermaid svg {
transform: scale(0.8);
transform-origin: top left;
}
- ❌ 結果：中の図が小さくなり隙間が増えただけ
試行5: pandocで出力
pandoc input.md -o output.pdf --pdf-engine=xelatex
- ❌ 結果：mermaidの図として認識するのに別ツールのインストールが必要（pandocとlatexだけではコードブロックになってしまった）
参考情報
VSCode Markdown PDF設定
{
"markdown-pdf.format": "A4",
"markdown-pdf.styles": ["custom.css"],
"markdown-pdf.includeDefaultStyles": true
}
Mermaid設定パラメータ
-
fontSize: 文字サイズ（全体のサイズに影響） -
nodeSpacing: ノード間の横間隔 -
rankSpacing: ノード間の縦間隔 -
theme: テーマ（base, default, dark, forest, neutral）
参考リンク
- Mermaid Live Editor: https://mermaid.live/
- Mermaid公式ドキュメント: https://mermaid.js.org/
- Markdown PDF GitHub: https://github.com/yzane/vscode-markdown-pdf
動作環境
- Markdown PDF: v1.5.0
- Mermaid:10.4.0
備考：検討したが解決したので試さなかった方法
試す前に解決したので実施しなかったが考えていたものを供養として掲載
1. Mermaid図を画像化
- Mermaid Live Editor (https://mermaid.live/) でPNG/SVG出力
- Markdownに画像として埋め込み
- ✅ 最も確実だが、手間がかかる
そもそも社外秘など機密情報を扱う場合はオンラインにあげてしまうと問題が発生するので、この方法を使うときはアップロードしてもいいものか確認すること
2. HTMLタグで囲む
<div style="max-width: 180mm; max-height: 250mm; margin: 0 auto;">
```mermaid
...
```
</div>