Creating Mermaid Diagrams in Notion

Introduction

Notion has become one of the most popular workspace tools for teams and individuals. While it doesn't have native Mermaid rendering like GitHub or Obsidian, there are effective ways to create and display Mermaid diagrams in Notion. This guide covers the available methods, their limitations, and the best workarounds.

Does Notion Support Mermaid Natively?

As of early 2026, Notion has added native Mermaid support through its code block feature. You can create a code block, select "Mermaid" as the language, and Notion will render the diagram inline.

Here's how to add a Mermaid diagram in Notion:

1. Type /code in any Notion page to insert a code block.
2. Click the language selector in the top-right of the code block.
3. Search for and select "Mermaid".
4. Paste or type your Mermaid code.
5. The diagram renders automatically below the code.

Example

Paste this into a Mermaid code block in Notion:

graph TD
    A[Task Created] --> B{Assigned?}
    B -->|Yes| C[In Progress]
    B -->|No| D[Backlog]
    C --> E{Done?}
    E -->|Yes| F[Complete]
    E -->|No| C

You should see a rendered flowchart directly in your Notion page.

Supported Diagram Types in Notion

Notion's Mermaid integration supports the most common diagram types:

• Flowcharts (graph / flowchart)
• Sequence Diagrams (sequenceDiagram)
• Gantt Charts (gantt)
• Class Diagrams (classDiagram)
• State Diagrams (stateDiagram-v2)
• ER Diagrams (erDiagram)
• Pie Charts (pie)

Mind maps, git graphs, and some newer diagram types may have limited support depending on the Mermaid version Notion uses.

Practical Use Cases in Notion

Team Wiki — Architecture Docs

Create a page in your team wiki with architecture diagrams:

graph TB
    subgraph "Client Layer"
        Web[Web App]
        Mobile[Mobile App]
    end
    subgraph "API Layer"
        Gateway[API Gateway]
        Auth[Auth Service]
    end
    subgraph "Data Layer"
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end
    Web & Mobile --> Gateway
    Gateway --> Auth
    Gateway --> DB
    Gateway --> Cache

Sprint Planning

Add a Gantt chart to your sprint page:

gantt
    title Sprint 16 — March 3-14
    dateFormat YYYY-MM-DD
    excludes weekends

    section Frontend
    Search feature     :f1, 2026-03-03, 3d
    Filter UI          :f2, after f1, 2d

    section Backend
    Search API         :b1, 2026-03-03, 4d
    Indexing           :b2, after b1, 2d

    section QA
    Testing            :q1, after f2 b2, 2d
    Release            :milestone, m1, after q1, 0d

Meeting Notes

Document decisions with sequence diagrams:

sequenceDiagram
    participant PM as Product Manager
    participant Dev as Dev Lead
    participant Design as Designer

    PM->>Dev: Propose feature X
    Dev->>PM: Estimate: 2 sprints
    PM->>Design: Request mockups
    Design-->>PM: Mockups ready
    PM->>Dev: Approved — start Sprint 17

Database Documentation

Use ER diagrams to document your data model:

erDiagram
    WORKSPACE ||--o{ PROJECT : contains
    PROJECT ||--o{ PAGE : has
    PAGE ||--o{ BLOCK : contains
    WORKSPACE ||--o{ MEMBER : has
    MEMBER {
        string id PK
        string name
        string email
        string role
    }
    PAGE {
        string id PK
        string title
        string content
        datetime updated
    }

Limitations of Mermaid in Notion

1. Version Lag

Notion may not run the latest version of Mermaid.js. This means some newer features or diagram types might not be available. If a diagram works in an online editor but not in Notion, this is likely the reason.

2. Limited Styling

Custom CSS styling through classDef and style directives may not render exactly as expected. Notion applies its own styling layer, which can affect colors, fonts, and spacing.

3. No Click Interaction

Mermaid diagrams in Notion are static images — you can't click on nodes or add links within the diagram. For interactive diagrams, you'll need a dedicated tool.

4. Dark Mode Compatibility

If you or your team uses Notion in dark mode, some Mermaid color schemes may not look great. Test your diagrams in both modes if your team uses both. Using Mermaid's built-in theme configuration can help:

%%{init: {'theme': 'neutral'}}%%
graph TD
    A --> B --> C

The neutral theme tends to work well in both light and dark modes.

5. Export Limitations

When exporting Notion pages to PDF or Markdown, Mermaid diagrams may export as code blocks rather than rendered images. Keep this in mind if you need to share pages outside of Notion.

Workarounds for Better Diagrams

Method 1: External Editor + Image Embed

For complex diagrams or when you need precise control:

1. Create your diagram in an online Mermaid editor.
2. Export as SVG or PNG.
3. Upload the image to your Notion page.
4. Keep the Mermaid source code in a collapsed toggle block for future editing.

This gives you the best visual quality and full Mermaid feature support.

Method 2: Embed with URL

Use an embeddable Mermaid viewer:

1. Encode your diagram.
2. Create a URL with the encoded diagram.
3. Use Notion's /embed block to embed the URL.

This approach keeps the diagram live and editable through the URL.

Method 3: Use Notion API + Mermaid

For teams that want automated diagrams, you can use the Notion API to programmatically insert and update Mermaid code blocks. This is useful for:

- Auto-generating architecture diagrams from code

- Updating project timelines from your PM tool

- Syncing database schemas with documentation

Tips for Mermaid in Notion

1. Keep diagrams simple. Notion's rendering area is narrower than a full browser window. Stick to 10-15 nodes max.

1. Use graph LR (left-to-right) for wider diagrams that fit Notion's column layout better than top-to-bottom.

1. Add context with text. Always include a text description above or below the diagram explaining what it shows.

1. Use toggle blocks. Put complex diagrams inside Notion toggle blocks (callouts) so they don't dominate the page.

1. Test in both themes. If your team uses both light and dark mode, check that your diagrams look acceptable in both.

1. Use the neutral theme. It provides the best compatibility across Notion's light and dark modes.

1. Keep source code accessible. If you embed an image instead of using a code block, store the source Mermaid code in a toggle block nearby so anyone can update it.

Notion vs. Other Platforms for Mermaid

Notion strikes a good balance between diagram support and collaboration features. While its Mermaid rendering may not be as polished as GitHub's, the collaborative editing and rich surrounding content make it a strong choice for team documentation.

Conclusion

Mermaid diagrams in Notion are a practical way to add visual documentation to your workspace. While there are some limitations compared to dedicated diagramming tools, the convenience of having diagrams alongside your team's notes, wikis, and project management makes it worthwhile. Start with simple flowcharts and sequence diagrams, and use the workarounds for more complex visualization needs.

Create and test your Mermaid diagrams in our free online editor →