How to Export Mermaid Diagrams from Markdown to PDF

Keep diagrams in the Markdown source

Mermaid turns text in a fenced code block into diagrams. This makes architecture and process diagrams easier to review in Git alongside the rest of a specification. For PDF output, use a Markdown renderer that converts Mermaid to SVG, wait for rendering to finish, and then print or export the resulting HTML.

```mermaid
flowchart LR
  A[Request] --> B{Approved?}
  B -- Yes --> C[Execute]
  B -- No --> D[Return]
```

If you see code rather than a diagram, check the mermaid language tag and that both code fences use the correct number of backticks.

Design for the printed page

Keep node labels short and move detailed explanations into prose below the diagram. flowchart LR runs left to right, while flowchart TD runs top to bottom; TD often fits portrait pages better. Split a large diagram into an overview and one or more detail diagrams instead of shrinking everything until labels become unreadable.

If a diagram overflows, shorten labels, switch direction, divide the flow, try landscape paper, and then adjust its preview width if needed. Place a page break before the diagram when its heading would otherwise be left on the previous page.

Before sharing, verify that every diagram rendered, non-Latin labels are correct, arrows do not overlap labels, nothing is clipped, and the meaning survives grayscale printing. Do not rely on color alone—add text labels such as “success” and “error.”

Diagnose Mermaid that remains as code

Confirm that the opening fence is followed immediately by the lowercase language identifier mermaid. The closing fence must contain the same number of backticks and no language name. A missing fence can make the rest of the document part of the diagram source. Test the diagram in a small file to separate Mermaid syntax errors from page-layout problems.

Node labels containing punctuation can require quotes. Keep node IDs simple and unique, then put the readable text inside brackets. Build the smallest valid diagram first and restore subgraphs, styles, and long labels one at a time. The first restored line that breaks rendering identifies the syntax problem.

Choose a direction that matches the paper

flowchart TD or TB usually suits portrait pages because the diagram grows downward. LR often suits a wide process or landscape page, but too many stages can still become unreadable. Direction is not merely decoration: it determines label width, edge length, and how much the browser must shrink the final SVG.

Split a large system into an overview and focused detail diagrams. Give each figure a descriptive H2 or H3 heading and explain important decisions in text. A diagram should support the document rather than becoming the only source of requirements.

Keep diagrams readable after export

Select the diagram in preview and resize it from a corner while preserving its aspect ratio. Centering works well for most flows; left alignment can suit a small diagram followed by related text. Add a page break before the image-like diagram when its title would otherwise be stranded on the previous page.

Color may change in grayscale printing or high-contrast viewing. Pair color with labels, borders, line styles, or icons. Use sufficient contrast and avoid very pale connector lines. Check Japanese and other non-Latin labels with the final PDF font because fallback metrics can move or clip text.

Mermaid PDF preflight checklist

• Every fenced block renders as a diagram.
• Node labels and edge labels are not clipped.
• The direction fits the selected page shape.
• Text remains readable at 100% PDF zoom.
• Meaning does not depend on color alone.
• The heading stays with the diagram.
• Large diagrams are divided into overview and detail views.
• The saved PDF, not only preview, has been checked.

Frequently asked questions

Why is a diagram blank in PDF but visible in preview?

Wait for Mermaid rendering to finish before opening the print dialog. A very large diagram may also exceed the printable area; simplify it or reduce its preview width.

Can Mermaid links remain clickable?

Link behavior depends on Mermaid security settings, sanitization, and the PDF print path. Do not rely on a clickable node as the only way to reach essential information; provide a normal Markdown link nearby.

See why Mermaid helps documentation for guidance on deciding which diagrams belong in a maintained specification.