用 VS Code 写完 Markdown,下一步若要交付 PDF,Markdown PDF 是常见的扩展。文本和代码通常能顺利导出;文档里若放了 Mermaid 图,结果却可能只剩源代码或空白页。这篇记录当时遇到的状况,以及可以先试的设置。
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
这段代码在网页中会显示成下图:
VS Code 预览面板可能显示正常,导出 PDF 时却出现两种情况:
-
完全没反应:原本的 Mermaid 区块在 PDF 中被解析为纯文本,没有图表渲染。
graph TD A --> B A --> C B --> D C --> D -
炸弹图标+空白页:PDF 内只看得到 “💣” 或整页空白,Mermaid 文本原样出现。
相关 issue 指向 Markdown PDF 与较新 Mermaid 版本之间的兼容性问题。
从 issue 的回报看,换用特定 Mermaid 版本的网址后,有些图表能恢复导出;不同版本与图表类型的结果却不一致。这表示问题和导出时加载的 Mermaid 脚本有关,不能只凭预览正常就判定 PDF 一定能用。
解决方案
可以先到设置页面找到 markdown-pdf.mermaidServer,指定 Mermaid 10.3.1,如下图:
把原本默认的网址:
https://unpkg.com/mermaid/dist/mermaid.min.js
取代成:
https://unpkg.com/[email protected]/dist/mermaid.js
其他版本可行吗?
GitHub 上也有相关的回报:
- Markdown-pdf: Mermaid Server VSCode URL no longer resolves #312
- [BUG] Mermaid Diagrams Not Rendered in Exported PDF #342
以下两则是蛮多人推荐的解决方案:
当时测试的版本中,10.3.1 能正常导出 Graph、sequenceDiagram 和 gantt。classDiagram、stateDiagram 等格式没有在这次测试范围内;升降版前,最好先用手上的图表各导出一次确认。
这个设置适合排查相同的导出症状。若扩展或 Mermaid 版本已更新,仍应以实际产出的 PDF 为准。
