Mermaid to PDF Without Screenshots
Most converters screenshot your diagram. Here is what that costs, and how to tell whether a PDF will survive zooming, printing and a failed render.
On this page
The screenshot problem
Ask a converter to put a Mermaid diagram in a PDF and most will do this: open a headless browser, render the diagram, capture the pixels, and place the image on the page.
It looks fine at 100%. Then you zoom in to read a label, print it on paper, or send it to a colleague who opens it on a 4K screen. Every edge turns soft, every 12px label turns grey, and the diagram — usually the part that explains the system — becomes the least readable thing in the document.
This is not a rendering bug. It is a format decision.
What vector actually changes
A vector diagram is stored as paths and text, not pixels. The PDF keeps:
- the shape geometry, so edges stay sharp at any zoom;
- real text for labels, so they remain selectable and searchable;
- one object graph per diagram, so a 40-node flowchart does not inflate the file.
In practice the difference shows up in three places: zooming, printing, and copying a label out of the PDF into a ticket. A bitmap fails all three.
The three failure modes worth checking
| What goes wrong | What you see | What to check before committing |
|---|---|---|
| Screenshot instead of vector | Blurry labels when zoomed; file size grows with diagram area | Ask whether the exporter produces SVG or embeds a bitmap |
| Missing fonts | Labels fall back to a default face; text overflows boxes | Are diagram fonts bundled with the renderer, or borrowed from the host |
| Silent render failure | A blank area, or the raw fence, with no warning | Does a failed diagram leave a diagnostic instead of disappearing |
The third one matters most in production docs. A diagram that fails loudly is an inconvenience; a diagram that fails silently ships an empty box to a customer.
What the source looks like
The Markdown stays untouched — the fence is the same one GitHub renders:
flowchart LR
A[Browser] --> B[Edge]
B --> C[API]
C --> D[(Postgres)]
C --> E[Queue]
E --> F[Worker]
Nothing in that block is specific to one tool. That is the point: the diagram belongs to the document, not to the exporter.
A short checklist
- Render the sample at 200%. If the labels are still crisp, the exporter is producing vectors.
- Search for a node label in the PDF. If the find box cannot locate "Postgres", the text is pixels.
- Break the diagram on purpose. Remove an arrow target and export again; you want a visible error or the source block, not an empty gap.
- Print page 1 on A4. Screen rendering hides thin strokes that printers lose.
How to try it on your own diagram
The Mermaid sample below walks through the same checks. If you want to start from a working document instead of an empty editor, open the Mermaid sample — it already contains a flowchart and a sequence diagram, and you can export it to see the output before pasting your own.
For diagrams mixed with formulas and tables, use the same editor and review the PDF feature set.
What we do not claim
Mermaid has more than thirty diagram types, and not every one survives every theme or page size. Unsupported syntax, invalid edges and oversized diagrams can still fail — the difference is that they fail with a diagnostic you can act on, and that most diagrams render as vector output. Diagrams built from HTML labels (for example journey) use a high-resolution image instead of vector paths.
This article is one part of a wider checklist: Markdown to PDF: tables, diagrams and equations covers tables, diagrams and equations together, and how to decide what to fix first.
The same renderer is one click away. Open a working sample and export it before pasting your own Markdown.