How Notion renders Mermaid
Notion renders Mermaid through code blocks: create a code block and set its language to Mermaid. The block can show the code, the rendered diagram, or a split view.
Rendering happens inside the Notion app with a Mermaid version bundled by Notion, updated on Notion's release schedule rather than yours.
flowchart TD
note[Notion code block] --> lang[Language: Mermaid]
lang --> view[Preview or split view]What works well
The stable core types — flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, pie — render dependably inside pages, and diagrams follow Notion's light and dark themes.
For meeting notes, specs, and wikis, small and medium diagrams are perfectly at home in Notion.
What to watch out for
Newer diagram types only appear after Notion updates its bundled Mermaid; there is no way to upgrade it yourself. If a type renders in your local editor but not in Notion, this is why.
Interactive click directives do not work.
Custom theme directives fight with Notion's own theming; diagrams that rely on specific colors may look different in dark mode.
Very wide diagrams are constrained by Notion's column width — they scale down and labels become small. Favor top-down layouts for tall, narrow content columns.
Exporting a Notion page to PDF or markdown does not always preserve rendered diagrams the way you expect — for share-critical documents, embed an exported SVG or PNG image instead.
Recommended workflow
Draft and validate in the MermaidPen studio, keep the markdown-safe preset on to bias toward widely supported syntax, then paste into a Notion Mermaid code block.
When a page must look identical for every reader (client-facing docs, handbooks), export PNG from the studio and use the image block, keeping the Mermaid source in a toggle underneath for future edits.