VS Code で Markdown を PDF に書き出す際、Mermaid 図を含む文書だけ失敗することがあります。Markdown PDF で図がソースのまま表示されたり、空白ページになったりした場合に試せる設定をまとめます。
Markdown PDF
拡張機能のページは次のとおりです:
Markdown PDF の利点は以下の通りです:
- VS Code の Command Palette → “Markdown PDF: Export (pdf)” を直接呼び出すだけで PDF が生成でき、HTML / PNG / JPEG など多様な出力形式に対応しています。
- 内蔵の puppeteer により、ヘッドレス Chrome で HTML → PDF のレンダリングが行われるため、数学式(KaTeX)、コードブロックのシンタックスハイライト、CSS テーマが正しく保持されます。
- Mermaid Server の URL をカスタマイズ可能であり、これが後述するエクスポートエラー修正の鍵となっています。
インストール後、settings.json にいくつかの設定項目が追加されますが、本記事では markdown-pdf.mermaidServer に注目します。
Mermaid エクスポートエラー
Markdown 内に以下のような記述がある場合:
graph TD
A --> B
A --> C
B --> D
C --> D
当サイトの基本機能を借りて上記を Mermaid 図としてレンダリングすると、以下のようになります:
使用上は特に問題なく、VS Code のプレビュー画面にもエラーは出ませんが、PDF エクスポート時には以下のいずれかの現象が発生します:
-
全く反応しない:元の Mermaid ブロックが PDF 内で単なるテキストとして扱われ、図がレンダリングされません。
graph TD A --> B A --> C B --> D C --> D -
爆弾アイコン+白紙ページ:PDF 内に “💣” マークのみ表示されるか、ページ全体が空白になり、Mermaid の記述がそのまま表示されます。
関連する issue では、Markdown PDF と新しい Mermaid の互換性が指摘されています。
issue の報告では、Mermaid のスクリプト URL を変えると表示が戻る図もありますが、結果はバージョンと図の種類によって異なります。書き出し時に読み込むスクリプトを確認し、プレビューだけで PDF の結果を判断しないほうが確実です。
解決策
設定画面で markdown-pdf.mermaidServer を探し、これを Mermaid 10.3.1 のバージョンに指定します。以下の画像のように設定してください:
デフォルトの URL:
https://unpkg.com/mermaid/dist/mermaid.min.js
を
https://unpkg.com/[email protected]/dist/mermaid.js
に置き換えます。
他のバージョンは使えるか?
GitHub 上で関連 issue をいくつか確認しました。代表的なものは以下です:
- Markdown-pdf: Mermaid Server VSCode URL no longer resolves #312
- [BUG] Mermaid Diagrams Not Rendered in Exported PDF #342
下記の 2 つは多くのユーザーが推奨する解決策です:
当時試したバージョンでは、10.3.1 で Graph、sequenceDiagram、gantt を正常に書き出せました。classDiagram や stateDiagram などは今回の確認範囲外です。バージョンを変更したら、使用する図の種類ごとに PDF を一度確認すると安心です。
拡張機能や Mermaid の更新後は結果が変わる可能性があります。最終的には生成された PDF を確認してください。
