Mermaid diagrams,
printed properly

Mermaid decides how big every box should be by measuring the width of the text that goes inside it. That measurement is the whole problem. If it happens before the web font has finished loading, the boxes are sized against a fallback font with different metrics, and the real text is then drawn into a box that was measured for something narrower. The label is clipped mid-word, and because the layout is already committed nothing later can rescue it.

• Labels cut off part-way through a word — the classic symptom, and the reason exports from comparable tools show boxes reading "Normalized subscriptic" or "Apple App Sto"
• Diagrams exported as raster images, which look acceptable on screen and print soft and blurry
• Diagrams dropped entirely, leaving a silent gap where the chart should be, with no error to tell you
• Arrows that land in the wrong place because the node they point at was measured at the wrong size

The typefaces are loaded and confirmed ready before a single diagram is drawn, so every measurement is taken against the font that will actually be used. The diagram is then rendered as SVG and embedded as vector art rather than a screenshot. Two things follow from that: it stays sharp at any zoom or print resolution, and the label text remains real text — selectable, searchable, and readable by a screen reader.

The most common kind, and the one most likely to expose the label-measurement bug because node labels vary so much in length. Node shapes, edge labels, and subgraphs all export intact.

```mermaid
flowchart TD
    A[Upload Markdown] --> B{Contains diagrams?}
    B -- Yes --> C[Load fonts first]
    B -- No --> D[Render text only]
    C --> E[Draw Mermaid as SVG]
    E --> F[Embed as vector art]
    D --> F
    F --> G[(Download PDF)]
```

Participant boxes, activation bars, loops and notes all survive. Long participant names are the usual failure case elsewhere, because the lifeline spacing is calculated from the measured name width.

```mermaid
sequenceDiagram
    participant B as Browser (your machine)
    participant S as Render service
    participant C as Headless Chrome
    B->>S: POST /api/render with Markdown
    S->>C: Load print stage
    activate C
    loop For each diagram
        C->>C: Measure labels, draw SVG
    end
    C-->>S: Tagged PDF
    deactivate C
    S-->>B: application/pdf
    Note over B,S: Nothing is written to disk
```

The structural diagram types export the same way. Class members and their visibility markers, state transitions, and ER cardinality notation all keep their formatting.

```mermaid
erDiagram
    DOCUMENT ||--o{ HEADING : contains
    DOCUMENT ||--o{ DIAGRAM : contains
    DOCUMENT {
        string title
        int pageCount
    }
```

```mermaid
stateDiagram-v2
    [*] --> Editing
    Editing --> Rendering: Download PDF
    Rendering --> Editing: Error
    Rendering --> [*]: File returned
```

Both are supported, and both are worth checking in the preview before exporting. A Gantt chart is usually the widest thing in a document, and a pie chart with long slice labels is the other common place clipping used to appear.

```mermaid
gantt
    title Release plan
    dateFormat YYYY-MM-DD
    section Writing
    Draft the spec      :done,    des1, 2026-01-05, 10d
    Review              :active,  des2, after des1, 5d
    section Build
    Implementation      :         des3, after des2, 20d
    Ship                :milestone, after des3, 0d
```

A flowchart with many parallel branches can be wider than the printable area, and this is the one case where a diagram needs help from you. It is scaled down to fit rather than being cropped, so nothing is lost, but scaled far enough the labels become uncomfortable to read. Three things fix it: switch the page to landscape in the style panel, change the flowchart direction from LR to TD so it grows downward instead of sideways, or split it into two diagrams. The preview shows the real printed width, so you can see which is needed before exporting.

A diagram is never sliced in half. One that will not fit in the space remaining on a page moves whole to the next one, which is why a document with several large charts sometimes has more white space at the foot of a page than you would expect. That is deliberate: half a flowchart is worth less than a short page.

Mermaid is strict about syntax, and a stray character is enough to break a chart. Rather than dropping it silently or failing the whole export, the diagram's source is printed in its place, so you can see exactly what was fed in and where it went wrong. One broken diagram never costs you the rest of the document.

• Check the first line names a diagram type — flowchart, sequenceDiagram, erDiagram and so on
• Quote labels containing brackets, colons or hyphens, which otherwise read as syntax
• Keep node ids free of spaces; put the spaces in the label instead, as in A[My label]
• Indentation is not significant, but a missing arrow head such as -> where --> is meant will stop the parse