SolConverter

technical how to

How to Export Mermaid Diagrams from Markdown to PDF

Learn how to render Mermaid diagrams before PDF capture, preserve SVG quality, isolate failures, and avoid CDN-dependent exports.

By SolConverter Team Updated 5 min read

Convert Markdown to PDF

To export Mermaid diagrams from Markdown to PDF reliably, detect Mermaid code fences, render each diagram before the PDF snapshot, wait for the SVG to settle, constrain it to the printable width, and isolate errors so one invalid diagram does not stop the document.

The most common failure is timing: the converter prints the page while Mermaid is still loading or rendering.

Start with the complete Markdown-to-PDF guide.

Why do Mermaid diagrams disappear in PDF exports?

A Markdown parser initially sees a Mermaid block as fenced source:

```mermaid
flowchart LR
  A[Markdown] --> B[Mermaid]
  B --> C[PDF]
```

A diagram library must then:

  1. parse the Mermaid syntax;
  2. calculate layout;
  3. create SVG;
  4. load any required fonts or styles;
  5. insert the result into the document.

If PDF generation begins between these steps, the exported file may contain:

  • raw Mermaid source;
  • an empty container;
  • a partially laid-out diagram;
  • a missing font;
  • a network error placeholder.

What is the correct rendering sequence?

Use this sequence:

  1. Parse Markdown.
  2. Identify Mermaid fences.
  3. Replace each fence with an isolated diagram container.
  4. Load a pinned Mermaid build.
  5. Render each diagram independently.
  6. Wait for all diagram promises.
  7. Wait for fonts and images.
  8. verify that each diagram container contains completed SVG or fallback content.
  9. Print the PDF.

Do not rely only on a generic “network idle” event. A page can be network-idle while a client-side layout task is still running.

Should Mermaid be loaded locally or from a CDN?

Both approaches can work, but they have different operational risks.

The current VS Code Markdown PDF documentation says its Mermaid library URL defaults to a CDN. That is convenient for an editor extension, but a backend service may prefer a bundled version so exports do not depend on a third-party network request.

Bundling Mermaid locally provides:

  • a pinned version;
  • reproducible output;
  • fewer external requests;
  • clearer content-security policy;
  • less exposure to CDN availability or version drift.

SolConverter currently bundles Mermaid 11 in the renderer.

Why use SVG for diagrams?

SVG is usually the best fit for technical diagrams because text and lines remain sharp when zoomed or printed.

A renderer should apply:

  • max-width equal to the printable content width;
  • automatic height;
  • overflow handling;
  • page-break avoidance where possible.

A very wide diagram may still need landscape orientation or a redesigned layout. Scaling a complex architecture diagram too aggressively can make labels unreadable.

What should happen when one Mermaid diagram is invalid?

One invalid diagram should fail locally.

Recommended behavior:

  • show a clear fallback message;
  • preserve the original Mermaid source;
  • record the parsing error;
  • continue with the next block.

This is especially important for generated documents. A report containing ten diagrams should not disappear because diagram four contains a typo.

SolConverter currently renders diagrams independently. A failed block is replaced with fallback content, while later diagrams continue.

Can ZenUML be exported with Mermaid?

SolConverter currently registers ZenUML as a Mermaid external diagram and bundles it locally. This allows supported ZenUML blocks to follow the same rendering lifecycle as Mermaid diagrams.

Do not generalize this to every Mermaid external diagram or UML language. Test the specific syntax and version used in production.

Does SolConverter support PlantUML or Graphviz?

Not currently.

The current non-claims include:

  • PlantUML;
  • Graphviz/DOT;
  • WaveDrom;
  • Nomnoml;
  • BPMN XML;
  • D2;
  • full TikZ.

This matters because other tools may be a better fit when a document depends on those diagram languages. Markdown Preview Enhanced, for example, documents a much broader diagram and local-toolchain ecosystem.

How should Mermaid diagrams behave in long PDFs?

Treat each diagram as a figure:

  • avoid splitting it across pages when it fits on one page;
  • keep a caption with the diagram;
  • repeat surrounding context in text;
  • provide descriptive alt or fallback text;
  • use landscape mode for intentionally wide diagrams.

Do not place essential meaning only inside a diagram. A diagram is useful evidence, but nearby text should explain the conclusion.

Test fixture for Mermaid export

Use at least four blocks.

1. Simple flowchart

flowchart LR
  A[Markdown] --> B[Render]
  B --> C[PDF]

2. Sequence diagram

sequenceDiagram
  participant Client
  participant API
  participant Renderer
  Client->>API: Create export job
  API->>Renderer: Render Markdown
  Renderer-->>API: PDF artifact
  API-->>Client: Expiring download URL

3. Wide architecture diagram

Create a diagram wide enough to test SVG scaling and landscape output.

4. Deliberately invalid diagram

flowchart LR
  A[Start --> B[Broken]

Place a valid diagram after the invalid one. The valid diagram must still render.

Mermaid troubleshooting checklist

The PDF contains source code instead of a diagram

Confirm that the export path recognizes mermaid as a special fence and does not treat it as normal code.

The PDF contains a blank area

Wait for Mermaid rendering explicitly. Check browser console errors and confirm that the library loaded under the current CSP.

The preview works but PDF export fails

The preview and export may use different HTML, browser settings, library URLs, or timing rules.

The diagram is blurry

Export SVG instead of a low-resolution screenshot or PNG. If raster output is required, increase scale and verify print quality.

The diagram is clipped

Constrain SVG width, preserve aspect ratio, and test landscape orientation.

The first invalid diagram stops the rest

Render each block independently and catch errors at the block level.

When should you use a backend instead of an editor extension?

Use an editor extension when one person is manually exporting a local document.

Use a backend when you need:

  • user uploads;
  • scheduled reports;
  • batch generation;
  • consistent renderer versions;
  • access controls;
  • job progress;
  • expiring artifact links;
  • server-side security policy;
  • repeatable output across clients.

Read: How to build a Markdown-to-PDF API.

Frequently asked questions

Does Mermaid export directly to PDF?

Mermaid renders diagrams, usually as SVG; the surrounding application then includes that output in a PDF.

Can Mermaid work offline?

Yes, when the application bundles the required Mermaid assets locally.

Can one PDF contain multiple Mermaid diagram types?

Yes, subject to the Mermaid version and supported syntax. Test each diagram family used by your documents.

Can a malformed diagram be preserved?

Yes. A fallback can display the original source and error message while the rest of the document continues.

Is SVG always better than PNG?

SVG is generally better for sharp technical lines and text. PNG may still be useful when a downstream system does not support SVG reliably.

Next step

Test your actual architecture and sequence diagrams, not only a two-node flowchart.

Convert Markdown with Mermaid to PDF or review security controls for user-provided Markdown.

References