Practical diagram guide

Fix Mermaid parse errors, overflowing text and blank exports

A practical troubleshooting guide for Mermaid syntax errors, long labels, export formatting, and browser storage.

Start with the reported line

If a diagram stops rendering after an edit, undo the last change and add it back in smaller steps. Check the reported line and the line immediately before it. A missing closing quote or bracket can make the next line look like the source of the error.

The editor keeps the last successful preview when possible. Treat the stale-preview notice as a signal that the visible diagram does not yet match the source.

Text extends beyond a box

Use the Node Defaults font-size control instead of applying a font-size change after rendering. Boxes must be measured with the same text size that will be displayed. For long headings, use a deliberate line break such as <br/> inside a quoted label, or a Mermaid Markdown string that can wrap.

Increase spacing if neighboring nodes overlap. Increasing export padding adds space around the whole diagram; it does not enlarge individual node boxes.

Formatting disappears in another application

Export with the updated SVG path, which uses native SVG text instead of embedded HTML labels. If a receiving application substitutes a font, the appearance may still change. Use PNG when you need the recipient to see a fixed raster image. Keep the MMD source alongside the image so you can edit it later.

The editor will not load

The application loads Mermaid and supporting libraries from a CDN. Check your connection and whether your network blocks that CDN. The editor does not bundle a guaranteed offline installation. If a browser extension blocks a request, review the browser network error before retrying.

Protect work saved in your browser

Local projects belong to this browser profile and site origin. Clearing browser data, moving to another domain, or using a different device does not carry those projects over. Download a JSON project backup from Export before clearing storage. Copying a share link makes its diagram accessible to anyone who receives that link.

Try it in the editor

Try rich text and wrapping before exporting your diagram.

flowchart LR
  A["<b>Plan</b><br/>Define the scope"] --> B["<b>Build</b><br/>Implement and test"]
  B --> C["<b>Ship</b><br/>Review the result"]

Open this example Download .mmd

Opening the example lets you review it before replacing your current diagram.

Syntax reference: official Mermaid documentation.