Printdown
EN

Mermaid diagrams in Markdown: export them to PDF

By ·

A diagram often explains a process better than three paragraphs, but drawing it in a graphics app means exporting an image, pasting it in and redoing it whenever something changes. With Mermaid, you describe the diagram in a few lines of text inside your Markdown and the editor draws it. This guide gives you copy-paste examples of the most useful diagram types and explains what happens to them when you export a PDF.

Why draw diagrams as text

Mermaid is an open-source library that turns a short text description into a diagram. That has practical advantages:

  • Edits take seconds. Renaming a step or adding a branch is a one-line change, and the layout is recalculated for you.
  • The diagram lives inside the document, so there is no image file to keep in sync, and changes are easy to review in version control.
  • It travels well. GitHub, GitLab and Obsidian render the same blocks, so one source works in a README, in your notes and in a PDF.

The trade-off is control: Mermaid decides where the boxes go. For documentation and notes, that is usually a good deal.

Your first diagram

In the Markdown to PDF editor, a diagram is a fenced code block whose language is mermaid. The first line inside names the diagram type; the rest describes it:

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

The preview redraws the diagram as you type. The first diagram in a document can take a moment to appear, because the editor loads the Mermaid library only when it is needed. Write mermaid in lowercase: a block marked Mermaid is shown as plain code.

Examples you can copy

Each of these renders as it is. Paste one, then replace the labels with your own.

Flowchart: processes and decisions

```mermaid
flowchart TD
  A[Request received] --> B{Approved?}
  B -->|Yes| C[Order the parts]
  B -->|No| D[Reply with reasons]
  C --> E[Schedule the work]
```

TD means top-down and LR left to right. Square brackets draw a box, curly braces a decision diamond, and |text| labels an arrow.

Sequence diagram: who talks to whom

```mermaid
sequenceDiagram
  participant C as Customer
  participant S as Shop
  participant P as Payment provider
  C->>S: Place order
  S->>P: Charge card
  P-->>S: Payment confirmed
  S-->>C: Order confirmation
  Note over S,P: Retried up to 3 times
```

Solid arrows (->>) usually show requests and dashed ones (-->>) replies. Every message needs a colon before its text.

Gantt chart: a project plan

```mermaid
---
config:
  gantt:
    useWidth: 640
---
gantt
  title Website relaunch
  dateFormat YYYY-MM-DD
  section Design
  Wireframes    :a1, 2026-11-02, 10d
  Visual design :a2, after a1, 8d
  section Build
  Development   :b1, after a2, 15d
  Testing       :b2, after b1, 5d
```

Each task has an ID, a start (a date or after another task) and a duration. The config header between the --- lines fixes the chart’s width, for reasons explained below.

Timeline: milestones

```mermaid
timeline
  title Project history
  2023 : Idea and first prototype
  2024 : Beta with 20 customers
       : First paid plan
  2025 : Version 2.0
```

Entity-relationship diagram: data models

```mermaid
erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ ORDER_LINE : contains
  PRODUCT ||--o{ ORDER_LINE : "appears in"
  CUSTOMER {
    int id
    string name
    string email
  }
```

|| means exactly one, o{ zero or more and |{ one or more. For object-oriented designs, classDiagram works in a similar way.

Pie chart and mind map

```mermaid
pie title Time spent per phase
  "Research" : 20
  "Design" : 30
  "Development" : 40
  "Testing" : 10
```
```mermaid
mindmap
  root((Trip to Lisbon))
    Travel
      Flights
      Airport transfer
    Stay
      Hotel
      Neighbourhood
    Budget
```

Pie values do not need to add up to 100. In a mind map, indentation alone defines the hierarchy, so keep it consistent.

Mermaid also draws state diagrams, user journeys, Git graphs, XY charts and Kanban boards. The editor uses Mermaid 12, and the official documentation covers every type.

How diagrams look on paper

Size and page width

Pages print in portrait, and the text column is about 17 cm wide on A4 with normal margins. A diagram that fits is printed at its natural size, centred and never enlarged. A wider one is scaled down to the column, and its text shrinks with it:

  • A left-to-right flowchart with more than three or four boxes in a row is already too wide. Changing LR to TD is usually the best fix.
  • Each participant in a sequence diagram adds about 5 cm; with five or six, the labels get small.
  • Timelines grow sideways with every period, so keep the event text short.

The Font size setting in the Style panel does not affect diagram labels; they only shrink when the diagram is scaled down. Most diagram types do use your theme’s body font, so they match the surrounding text.

Gantt charts need a fixed width

Mermaid sizes Gantt charts to your browser window, not to the page. On a wide screen the chart comes out very wide and is then shrunk to fit, leaving text too small to read. The useWidth setting in the example above fixes the width instead; 640 matches the column on A4 or Letter with normal margins.

Page breaks around big diagrams

The editor tries to keep each diagram on one page. If a diagram does not fit in the space left, it moves to the next page, which can leave a gap and separate it from its heading. Two habits help:

  • Put <!-- pagebreak --> on its own line before the heading of a section with a large diagram, so both start the next page together.
  • Keep every diagram shorter than a page. A taller one cannot stay together: the browser slices it where the page ends, sometimes through a box. Split it instead, for example into one diagram per phase.

Colours, themes and dark mode

Diagrams use Mermaid’s neutral theme: light grey boxes, dark text and grey lines, which print well even in black and white. They do not follow the colours you pick in the Style panel, and dark mode does not affect them: the preview page is always white and the PDF is always printed light. To restyle a single diagram, add a config header to its block:

```mermaid
---
config:
  theme: forest
---
flowchart LR
  A[Draft] --> B[Review] --> C[Publish]
```

default, forest and base add colour, and neutral restores the standard look. Avoid dark for print: its black boxes and pale arrows are meant for a dark background and waste ink on paper.

Vector or image?

With Download PDF and Save as PDF in the print dialog, diagrams stay vector graphics: lines are sharp at any zoom, and labels are real text you can select and search. (In Chrome, boxes with a soft shadow are embedded as high-resolution images, which you will not notice on paper.) More → Quick PDF (image) turns each page into a picture instead: nothing is selectable, the result is less sharp, and diagram labels may fall back to a default font. More → Download .html also keeps diagrams as vector graphics.

When a diagram does not render

If Mermaid cannot read a block, the diagram is replaced by red text starting with Mermaid:. Parse errors show the line number within the diagram and a caret where reading stopped; the rest of the document still renders. Fix it before exporting, because the PDF contains exactly what the preview shows. The usual causes:

  • “No diagram type detected”: the first line is missing or misspelled (flowchar, sequencediagram). Keywords are case-sensitive.
  • Brackets or parentheses inside a label, as in A[Send invoice (PDF)], give an error ending in got 'PS'. Quote the label: A["Send invoice (PDF)"].
  • A flowchart node called end breaks the diagram, because end is a keyword. Write End, or use it only as a label: Finish[end].
  • A sequence message without a colon (Alice->>Bob Hello) gives Expecting 'TXT', got 'NEWLINE'.
  • “Invalid date” in a Gantt chart: a date does not exist or does not match the dateFormat line.
  • Curly quotes (“ ”) pasted from a word processor do not count as quotes. Use straight ones in diagram code.

Still stuck? Remove lines from the end of the block until the diagram reappears; the last line you removed is the culprit.

Tips for diagrams that read well on paper

  • Short labels. Two to five words per box. Flowchart boxes wrap long text; to choose the break yourself, use <br>: A["First line<br>second line"].
  • Fewer than 15 boxes. Split a big process into an overview and one or two detail diagrams.
  • Introduce every diagram with a sentence that says what to look at.
  • Let labels carry the meaning, not colour alone: the PDF may be printed in black and white.
  • Use %% for comments. Those lines stay in the source but are not drawn.
  • Check the preview with your final theme. Mermaid measures labels before the document font is applied, so with the wider serif fonts of Classic and Editorial a short arrow label can lose its last letter. If that happens, switch to a sans-serif theme such as Modern or Clean.

Everything, diagrams included, is rendered in your browser; nothing is uploaded. For the rest of the syntax, see the Markdown guide. If your diagrams live in Obsidian, exporting Obsidian and Notion notes to PDF covers the other syntax worth tidying up.

More guides