How to export Mermaid diagrams to PDF without cropping or blurry output

Mermaid is ideal for diagrams that should live with your documentation: a flowchart, sequence diagram, ERD, or architecture map remains plain text until you need to share it. The hard part is the last step. A diagram can look perfect in a preview and still arrive in a PDF with clipped nodes, tiny labels, or screenshot-like blur.

This workflow keeps the full diagram on the page and the text sharp. Start with the Mermaid to PDF converter: paste your source, inspect the preview, choose the page that suits the diagram, then export. It runs in your browser, so internal architecture diagrams do not need to be uploaded to a conversion service.

How to export a Mermaid diagram to PDF

1. Open Mermaid to PDF and paste a Mermaid diagram or a Markdown document containing Mermaid fences.
2. Check the rendered preview before exporting. Fix syntax and make sure the outermost nodes are visible.
3. For a wide diagram, select landscape or simplify the diagram into a more vertical flow.
4. Export the PDF and open it at 100% zoom. Labels should be readable and no connector or node should touch the page edge.

The preview is the useful checkpoint: it separates a Mermaid layout problem from a page-layout problem. If an element is absent in the preview, adjust the source. If it is present there but cut off in the exported PDF, give the diagram more horizontal room or reduce its scope.

PDF vs SVG vs PNG: which format should you choose?

Use PDF when the diagram is a document deliverable: something to print, send, archive, or attach to a ticket. Use SVG when another design or documentation tool needs to reuse and scale the drawing. PNG is mainly for places that accept only raster images, such as a slide editor or a chat attachment.

For technical documentation, avoid making a PNG merely to put it in a PDF. That adds a raster step, so small text and fine connector lines can soften when somebody zooms or prints. A Mermaid PDF based on vector output preserves geometric lines and text much more cleanly.

Why Mermaid diagrams get cropped

Cropping is usually a mismatch between the diagram's bounding box and the printable page. A left-to-right graph can grow one node at a time until it is wider than a portrait page. Long labels, grouped subgraphs, wide sequence participants, and notes all increase that width.

Here is a typical before example. It is valid Mermaid, but six horizontal stages make it a poor portrait export candidate:

graph LR
  A[Browser] --> B[API gateway]
  B --> C[Authentication service]
  C --> D[Order service]
  D --> E[Inventory service]
  E --> F[Postgres database]

Before: a long left-to-right flow can force tiny type or a cropped right edge on a portrait page.

The first fix is landscape. The better fix, when readers need to understand the system rather than admire its width, is to split or regroup the stages:

flowchart TD
  A[Browser] --> B[API gateway]
  B --> C[Authentication service]
  B --> D[Order service]
  D --> E[Inventory service]
  E --> F[(Postgres database)]

After: a top-to-bottom flow uses the page height, keeps labels readable, and leaves a safe margin around the diagram.

Do not solve every width problem by shrinking the diagram. A PDF that technically contains every node but requires 200% zoom is not a successful export.

How to fix wide flowcharts and sequence diagrams

For flowcharts, try TD instead of LR, shorten node labels, and turn a large system map into one overview plus focused diagrams. Subgraphs are useful, but a row of many subgraphs can make a page just as wide as a row of nodes.

Sequence diagrams tend to expand horizontally because each participant takes a column. Keep the cast small, use aliases for long service names, and move ancillary details into a note or a second diagram. If a sequence spans several independent interactions, export one PDF with several smaller diagrams rather than one unreadable timeline.

Portrait vs landscape orientation

Choose orientation from the diagram's reading direction. Portrait works naturally for top-to-bottom flowcharts, state diagrams, and short ERDs. Landscape usually fits left-to-right flows, wide sequence diagrams, timelines, and Gantt charts. The correct choice is the one that lets a reader see labels at normal document zoom with clear whitespace around the outer edges.

If landscape still makes text too small, the issue is not the page setting. Reduce the number of simultaneous branches or split the diagram by responsibility, request, or lifecycle phase.

How to keep text and lines sharp

Keep the export vector-based and avoid screenshot workflows. Preview at the size at which the PDF will be read, not only while the browser has a large editor pane. Use concise labels and let the diagram have enough page space; shrinking a dense diagram is the fastest route to text that is technically present but practically illegible.

Also verify the finished PDF rather than only the source. Open it at 100% zoom and look for fuzzy type, missing arrowheads, overly thin lines, or clipped shadows near the boundaries. These are export issues, not Mermaid syntax issues.

Exporting Mermaid inside a Markdown document

Mermaid becomes especially useful when diagrams travel with explanations. Put the diagram in a fenced mermaid block in your Markdown, then export the complete document instead of managing a separate image file:

# Checkout request

The request is authorized before inventory is reserved.

```mermaid
sequenceDiagram
  Browser->>API: Place order
  API->>Auth: Verify session
  API->>Inventory: Reserve items
```

That approach keeps headings, decisions, code samples, and the diagram together. Use the Markdown to PDF converter for document-first exports, or the Mermaid tool when the diagram itself is the primary artifact.

Handling multiple diagrams in one PDF

Give every diagram its own short introduction and let each one start with enough space. A useful documentation sequence is an overview diagram first, then one diagram per flow or subsystem. Readers can orient themselves in the overview and inspect the details without decoding a single enormous graph.

Keep a consistent theme and direction where possible. For example, use top-to-bottom for all lifecycle flows and landscape only for sequence diagrams. Consistency makes a multi-page PDF feel intentional and makes bad page breaks easier to spot in preview.

Keep private architecture diagrams local

Mermaid source can expose service names, data stores, integrations, internal URLs, and security boundaries. Treat it like other technical documentation: use a local workflow when it contains non-public architecture. MarkDone renders Mermaid and creates the PDF in your browser, so the source stays on the device running the converter.

Final export checklist

• Preview the complete diagram before exporting.
• Use landscape for genuinely wide diagrams; otherwise prefer a clearer vertical layout.
• Keep node labels concise and split diagrams that require extreme scaling.
• Check the PDF at 100% zoom for clipped nodes, arrowheads, and text.
• Use vector PDF output instead of a screenshot when sharpness matters.
• For internal diagrams, use a local converter and review the source before sharing.

Once the layout is right, Mermaid gives you a shareable PDF without losing the editable source behind it. For the wider privacy trade-off, read how to convert Markdown to PDF without uploading your files.