How to Convert Markdown with Mermaid Diagrams to PDF

Mermaid lets you describe flowcharts, sequence diagrams, and Gantt charts as plain text inside fenced code blocks. The hard part is getting those diagrams to actually appear when you convert markdown to PDF. Most converters treat the Mermaid block as a literal code snippet — or require a plugin and config file before they’ll render it. This guide shows the painless way to do it, and why a browser-based tool handles Mermaid natively.

Why Mermaid is usually a hassle

A Mermaid diagram is written like this:

flowchart LR
    A[Write Markdown] --> B{Has Mermaid?}
    B -->|Yes| C[Render to SVG]
    B -->|No| D[Render text]
    C --> E[Export PDF]
    D --> E[Export PDF]

For a renderer to turn that into an actual diagram, it has to recognize the mermaid language tag, run the Mermaid engine on the contents, and embed the result in the page. Many tools skip this:

• Pandoc has no built-in Mermaid support. You need a filter such as mermaid-filter, which in turn shells out to a headless browser or the Mermaid CLI. That means extra installs and configuration.
• VS Code + “Markdown PDF” (yzane) can do Mermaid, but only after you enable the right setting and let it download a Chromium build on first run.
• Generic “paste your markdown” web converters often render the Mermaid block as a gray code box, not a diagram.

The no-setup approach

MarkdownToFile renders Mermaid natively in the browser. When you paste a mermaid fenced block, it runs the Mermaid engine on the fly and draws the diagram as vector SVG — so it stays sharp at any zoom and prints as crisp lines, not a blurry bitmap. There is nothing to install, no plugin to enable, and no config file.

The workflow is three steps:

1. Open the editor (or load a ready-made Mermaid example).
2. Paste your Markdown, including any ```mermaid blocks. The live preview redraws each diagram instantly.
3. Pick a theme and page size, then download. The Mermaid SVG is embedded directly in the vector PDF.

Because the preview is the document you download, what you see is exactly what lands in the PDF — no surprises about whether a diagram rendered.

How the options compare

Tool	Mermaid support	Setup required	Output quality
MarkdownToFile	Native, no config	None (runs in browser)	Vector SVG
Pandoc	Via mermaid-filter	Install Pandoc + filter + browser/CLI	Image (raster or SVG)
VS Code + Markdown PDF	After enabling setting	VS Code + extension + Chromium	Image
Generic web converters	Often none	None	Usually unrendered code block

Tips for clean diagram pages

• Keep one large diagram per section so it isn’t split across a page break.
• Try the Clean or GitHub theme for the most neutral diagram styling.
• For tall flowcharts, switch the page size to A3 or use wide margins to give the SVG room.
• If a diagram is very wide, flowchart LR (left-to-right) often fits a page better than top-down.

Where other tools win

If you need to generate hundreds of diagram-heavy PDFs from a script, Pandoc with mermaid-filter is the right call — it automates cleanly once configured. If you already work inside VS Code all day, the extension keeps everything in one window. MarkdownToFile’s edge is that it does Mermaid-to-PDF with zero setup and keeps your content private: nothing is uploaded, since the whole conversion happens client-side.

Bottom line

If you just want your Mermaid diagrams to show up correctly in a PDF without wrestling with plugins or installs, a browser tool is the fastest path. MarkdownToFile renders Mermaid to vector SVG natively, so the diagrams are searchable-document-quality and look right the first time.

Ready to try it? Open the Mermaid example in the editor or read more on the dedicated Mermaid to PDF page.