mdtopdf.

Document field notes

Mermaid diagrams that stay readable in a PDF

A page-first workflow for Mermaid flowcharts in Markdown: orientation, short labels, accessible titles and a final PDF legibility check.

Published 2026-10-24 · Markdown to PDF editorial

A Mermaid diagram can look correct in the editor preview and still arrive in the PDF as a cramped, oversized or awkwardly placed drawing. The preview pane and a printed page have different shapes, so the useful work happens before export: design the diagram for the page, then check the result in the downloaded file.

What the converter documents about Mermaid

Markdown to PDF lists Mermaid diagrams among its features, and its public product notes say diagrams written in ```mermaid fences are drawn as vector SVG and carried into the PDF. That is the product's own description, not an independent audit of every diagram type, theme or export path.

Two consequences follow from "vector SVG". First, the drawing is not a screenshot, so it can be scaled without pixel blur — but scaling does not make small labels easier to read. Second, the diagram is fitted to the space it is given, which means its own proportions decide how much of the page width it consumes. This guide focuses on that fitting problem rather than on Mermaid syntax in general.

Start with a diagram built for a portrait page

Use a small, realistic fixture instead of your longest diagram. The example below describes a review flow with six nodes, a single decision loop and an accessible title and description. Paste it into the editor and compare the preview with the exported file. If the diagram comes from confidential material, check the tool's own data-handling description before pasting; this guide does not certify confidentiality.

# Deployment flow

```mermaid
flowchart TD
  accTitle: Deployment approval flow
  accDescr: A change moves from draft to review, then to production only after approval.
  A[Draft change] --> B{Tests pass?}
  B -- Yes --> C[Editorial review]
  B -- No --> D[Fix and re-run]
  C --> E{Approved?}
  E -- Yes --> F[Publish]
  E -- No --> D
  D --> B
```

When this fixture was opened in the live preview in a desktop browser on 24 October 2026, the flowchart rendered with six nodes and seven connecting edges. The accessible title and description appeared as the SVG's title and desc elements. The diagram's text was rendered inside the drawing rather than as an ordinary paragraph. That browser check covered the preview only; it was not a download-and-inspect test of the PDF.

Choose the direction from the page, not the pane

Mermaid's flowchart documentation defines the available orientations: TD or TB for top to bottom, BT for bottom to top, RL for right to left and LR for left to right. The choice is usually made for on-screen reading, where a wide window is available. A portrait A4 or US Letter page inverts that assumption: width is the scarce dimension and height is comparatively generous.

In the same browser check, a three-stage flowchart LR line was scaled down to fit a preview pane roughly 560 pixels wide and ended up roughly as tall as a line of body text. Nothing was clipped, but the labels had been shrunk along with the drawing. Expect the same trade-off on a page: the wider the diagram's natural layout, the smaller its text becomes when it is fitted to the page width. For a linear process on a portrait page, flowchart TD is the safer default. Reserve LR for shallow, genuinely horizontal comparisons with very short labels.

Short labels survive shrinking

Node labels are the part of a diagram most likely to become unreadable. Write them as if they were table cells: a short noun phrase or a verb with its object. Move the explanation into the surrounding prose, where it is set at full body size and can wrap normally.

Mermaid supports markdown strings whose text wraps automatically inside node labels, but wrapping adds height and produces taller nodes. Long sentences, file paths and URLs in a node create the same problem in a different shape: a wide box that forces the whole drawing to shrink. The documentation also notes that end used as a node word should be capitalised, and that node identifiers beginning with o or x need a space or capital letter to avoid being read as edge syntax. In one small test here, a lowercase end label still rendered, so treat that warning as renderer-version dependent rather than universal.

Put the explanation in the diagram, not only beside it

A PDF is often read out of context: attached to a ticket, printed for a meeting or opened months later. A caption in the surrounding Markdown may not travel with a copied page. Mermaid's accessibility options let the diagram carry its own name and description. accTitle: takes a single line; accDescr: takes either a single line after a colon or a multi-line value wrapped in braces.

These are Mermaid features, so support depends on the renderer and its version; check that your diagram still shows the title and description after export. Use them as editorial content, not as a keyword field. "Deployment approval flow" and one sentence naming the actors and the decision are more useful than repeating the title of the document. The observed SVG carried both strings in this preview; whether a particular PDF viewer exposes them to assistive technology is a separate question that needs its own check.

Inspect the exported PDF, not only the preview

  1. Open the downloaded file at 100%. Compare the diagram's label height with the body text around it. If you have to zoom in to read a node, a reader who prints the page will struggle too.
  2. Inspect every page boundary. A tall top-to-bottom flow is the most likely candidate for being split or pushed to a new page. If a decision node and its two outgoing branches land on different pages, redraw or shorten the flow.
  3. Look at the widest row. Wide nodes, long edge labels and side-by-side branches are where clipping or aggressive shrinking shows up first.
  4. Check contrast in greyscale. Mermaid's default styling uses colour to distinguish elements. Print or preview the page in black and white and confirm the structure still reads from shape, labels and arrows rather than fill colour alone.
  5. Try selecting a label. Text extraction from an SVG-based drawing depends on the renderer, so do not assume the diagram's words are searchable or copyable. If the labels matter as text, repeat the key facts in a caption or a short list.

Diagnose a diagram that misbehaves

The fence appears as a code block
Check the language tag immediately after the opening backticks. In a browser check, a fence with no mermaid tag stayed a code block, while the tagged fence rendered. A typo or a stray space has the same effect.
The diagram is tiny
Its natural layout is wider than the page. Switch a linear flow from LR to TD, shorten labels, or split one large diagram into two smaller ones with clear names.
A node or edge is missing
Suspect the source before the exporter. Quote labels that contain brackets, braces or punctuation, and check the documented reserved words above.
The diagram runs to the page edge
Shorten the labels and remove optional detail first. Splitting the diagram is usually clearer than shrinking every node to fit.
The diagram renders but the meaning does not
That is an editorial problem, not a rendering problem. Name the decision, label both branches and state the outcome in words. A reader should not need the colour palette to follow the flow.

Delivery checklist

  • One diagram, one question. If it needs two readings to find the main path, split it.
  • Direction chosen for the page: TD for a portrait process, LR only for short horizontal comparisons.
  • Labels short enough to read at 100% after the drawing has been fitted to the page.
  • accTitle and accDescr written as a name and a one-sentence explanation.
  • Downloaded PDF inspected at every page boundary, in greyscale and at 100% zoom.
  • Key facts repeated in prose where the diagram's text cannot be relied on.

Sources and scope

Checked 24 October 2026. The workflow is editorial guidance. The preview observations come from one desktop browser session on that date; no benchmark, export-success rate or assistive-technology audit is claimed, and the PDF download itself was not part of that check.