ブログに戻る
一般記事

Markdown PDF Mermaid のエクスポートエラー修正

エクスポートエラーを修正し、Mermaid 図が正しく表示されるようにする。

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 内に以下のような記述がある場合:

text
graph TD
    A --> B
    A --> C
    B --> D
    C --> D

当サイトの基本機能を借りて上記を Mermaid 図としてレンダリングすると、以下のようになります:

ABCD
上方 Mermaid 程式碼對應的流程圖。

使用上は特に問題なく、VS Code のプレビュー画面にもエラーは出ませんが、PDF エクスポート時には以下のいずれかの現象が発生します:

  1. 全く反応しない:元の Mermaid ブロックが PDF 内で単なるテキストとして扱われ、図がレンダリングされません。

    text
    graph TD
        A --> B
        A --> C
        B --> D
        C --> D
    
  2. 爆弾アイコン+白紙ページ:PDF 内に “💣” マークのみ表示されるか、ページ全体が空白になり、Mermaid の記述がそのまま表示されます。

関連する issue では、Markdown PDF と新しい Mermaid の互換性が指摘されています。

issue の報告では、Mermaid のスクリプト URL を変えると表示が戻る図もありますが、結果はバージョンと図の種類によって異なります。書き出し時に読み込むスクリプトを確認し、プレビューだけで PDF の結果を判断しないほうが確実です。

解決策

設定画面で markdown-pdf.mermaidServer を探し、これを Mermaid 10.3.1 のバージョンに指定します。以下の画像のように設定してください:

デフォルトの URL:

text
https://unpkg.com/mermaid/dist/mermaid.min.js

を

text
https://unpkg.com/[email protected]/dist/mermaid.js

に置き換えます。

他のバージョンは使えるか?

GitHub 上で関連 issue をいくつか確認しました。代表的なものは以下です:

下記の 2 つは多くのユーザーが推奨する解決策です:

当時試したバージョンでは、10.3.1 で Graph、sequenceDiagram、gantt を正常に書き出せました。classDiagram や stateDiagram などは今回の確認範囲外です。バージョンを変更したら、使用する図の種類ごとに PDF を一度確認すると安心です。

拡張機能や Mermaid の更新後は結果が変わる可能性があります。最終的には生成された PDF を確認してください。