How to Use Mermaid Diagrams in Notion

Notion renders Mermaid on its own. Add a code block, pick Mermaid as the language, and the diagram appears in the page without an embed, an integration, or an image upload. Most people miss this because the language menu has dozens of entries and Mermaid sits far down the list.

The built-in renderer covers the common case well and falls short in a few predictable places: no theme control, no spacing control, and a Mermaid version that lags the current release. This post walks through the native route first, then the cases where an exported PNG or SVG from MermanDraw is the better choice.

Render Mermaid natively in a Notion code block

1. Type /code on a new line and press Enter.
2. Click the language label in the top-left corner of the block (it usually reads "Plain text" or "JavaScript") and choose Mermaid. Typing "mer" filters the list.
3. Paste your diagram code. Use the raw Mermaid source, not a Markdown fence. A leading ```mermaid line breaks the parser.
4. Use the Code / Preview / Split toggle at the top of the block. Split shows code and diagram side by side while you edit.

flowchart LR
    A[Write Mermaid in a code block] --> B{Language set to Mermaid?}
    B -- Yes --> C[Preview renders in place]
    B -- No --> D[Plain text only]
    D --> E[Change language to Mermaid]
    E --> C
    C --> F["Share page (diagram included)"]

Set the block to Preview before you share the page. Viewers see the diagram and never need to touch the toggle. The block behaves like any other: you can drag it into a column, duplicate it, or nest it in a toggle.

Light and dark mode

The preview follows Notion's appearance setting. In dark mode the renderer swaps to its dark palette: lighter strokes, darker fills. You do not control this per diagram, and a diagram that reads well in light mode can lose contrast in dark mode when you rely on fill colors through style or classDef. If a page is read by a team with mixed settings, keep custom fills light and test both modes.

What the Notion renderer cannot do

• No theme selection. There is no way to choose a palette, a font, or a background. The diagram looks like the Mermaid default in whichever mode the viewer uses.
• No layout control. Node spacing and rank spacing are fixed. Wide flowcharts squeeze into the column width and labels wrap.
• Older Mermaid version. Notion bundles its own copy of the library and updates it when it chooses. Types added in recent releases, such as architecture or packet diagrams, can fail with a syntax error that the same code does not produce elsewhere. The cheatsheet lists which types are mature.
• No zoom. A large sequence diagram is scaled to fit the block and the text becomes small. Full-width pages help, but there is no click-to-enlarge.
• Error messages are terse. A broken diagram shows a generic failure without a line number. Paste the code into the editor to see the offending line highlighted and, for common mistakes, a one-click fix.

PDF and HTML exports include the rendered diagram, so the native route is fine for pages that end up as documents.

When to insert an image instead

Three situations call for a PNG or SVG rather than the built-in preview:

• You need a specific look. Brand colors, a dark background on a light page, or a monochrome version for print. Render the code in MermanDraw, pick one of the seven themes, and export.
• The diagram appears in more than one tool. The same diagram in Notion, a slide deck, and a Confluence page should look identical. One exported image guarantees that; three renderers do not.
• The diagram is large. Twenty nodes or a sequence diagram with ten participants becomes unreadable inside a Notion column. A 2× PNG stays sharp when the reader opens it full screen.

Pick SVG when the page is read on screen and the diagram contains text you want crisp at any zoom. Pick PNG when the page is exported to PDF often or when other tools in the chain do not accept SVG. The export guide covers the trade-offs in more detail.

sequenceDiagram
    participant W as Writer
    participant N as Notion page
    participant M as MermanDraw
    W->>N: /code, language = Mermaid
    N-->>W: Code / Preview / Split toggle
    W->>M: Paste code for a custom theme
    M-->>W: PNG or SVG download
    W->>N: Drop image + keep code in a toggle

Keep the source editable

An image is a dead end unless the code travels with it. The pattern that holds up over time:

1. Insert the exported image.
2. Directly beneath it, add a toggle block titled "Diagram source" and put a Mermaid code block inside.
3. Optionally add a line with the MermanDraw share link so the next editor can open the diagram with the same theme and spacing already applied.

The toggle stays collapsed for readers, the code stays searchable, and anyone on the team can update the diagram without hunting for the original. For the type-specific syntax, the flowchart and sequence diagram guides cover the details, and the examples gallery has ready-made diagrams to start from.

FAQ

Related

• Where does Mermaid render natively? — tool-by-tool support list.
• Mermaid diagrams in Obsidian — setup, styling, export.
• Mermaid in Confluence and Jira — the macro route and the image route.