Fix Markdown PDF Mermaid Export Error

If you want to convert Markdown files to PDF, you will probably come across a few common tools.

I personally use the Markdown PDF extension in VS Code to export PDFs.

Markdown PDF

This extension looks like this on my system:

The advantages of Markdown PDF include:

Directly call VS Code’s Command Palette → “Markdown PDF: Export (pdf)” to generate PDFs, supporting multiple output formats such as HTML / PNG / JPEG.
Built-in puppeteer, which can render HTML → PDF in headless Chrome, so math formulas (KaTeX), code block highlighting, and CSS themes are all preserved perfectly.
Allows customizing the Mermaid Server URL, which is the key to fixing the export error below.

After installation, several properties appear in settings.json. This article focuses on markdown-pdf.mermaidServer.

Mermaid Export Error

When the Markdown contains the following syntax:

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

Using this site’s built-in feature to render the above as a Mermaid diagram looks like this:

Functionally, everything works fine — the VS Code preview panel shows no errors. However, exporting to PDF may result in two situations:

No response at all: The original Mermaid block is parsed as plain text in the PDF, without any diagram rendering.
```
graph TD
    A --> B
    A --> C
    B --> D
    C --> D
```
Bomb icon + blank page: The PDF shows only a “💣” icon or a blank page, with the Mermaid text appearing as-is.

After researching, the main cause seems to be a compatibility conflict between Markdown PDF and the latest Mermaid version.

Since Mermaid 10.4.0, the official release uses ES Module, and the old puppeteer evaluate() script injection fails to run properly, causing “syntax error in text” and empty rendering.

Solution

Here is the conclusion first:

Go to the settings page, find markdown-pdf.mermaidServer, and point it to Mermaid 10.3.1 version, as shown below:

Replace the original default URL:

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

with:

https://unpkg.com/mermaid@10.3.1/dist/mermaid.js

Are other versions feasible?

I searched GitHub for a while and found some related issues, such as:

Below are two commonly recommended solutions:

But from my own tests, only version 10.3.1 can correctly convert all my diagrams, including Graph, sequenceDiagram, and gantt. As for other diagram types like classDiagram, stateDiagram, etc., you may need to try them yourself.

Finally, if you have any good methods or successful experiences with other versions, feel free to share them in the comments.

☕ Fuel my writing with a coffee

Your support keeps my AI & full-stack guides coming.

All-in

AI / Full-Stack / Custom — All In

From idea to launch—efficient systems that are future-ready.

All-In Bundle

Consulting + Dev + Deploy
Maintenance & upgrades

🚀 Ready for your next project?

Need a tech partner or custom solution? Let's connect.

Fix Markdown PDF Mermaid Export Error

Markdown PDF​

Mermaid Export Error​

Solution​

Are other versions feasible?​