Mermaid Diagrams as Code in Notion

How to display lovely diagrams in Notion using Mermaid syntax

Mermaid Diagrams as Code in Notion

What is Mermaid

Mermaid JS is a library for building Diagrams as Code, similar to PlantUML.  You start by writing a set of code that describes how the diagram looks, then use the library to render it as a diagram.

For example, here is a basic flow chart in Mermaid syntax:

graph TD;

Which when rendered appears like this:

A more complex example may look like this:

%% Flowchart
graph TD
    A[Sunday] -->|Get money| B(Go shopping)
    B --> C{Are we out of milk?}
    C -->|Yes| D[Buy milk]
    C -->|No| E[Buy cookies]
    D --> E

In this example:

  • %% Flowchart is a comment
  • graph denotes the type of diagram to show
  • TD tells it to render top down (if I added LR it would place the boxes left to right)
  • A, B, C, D and E are all node identifiers, each a box to show
  • --> creates an arrow between two nodes
  • [Label] creates a square box with that text inside it
  • (Label) creates a rounded box with that text inside it
  • {Label} creates a decision box with that text inside it
  • |Label| labels an arrow

What Types of Diagram Does Mermaid Support?

Mermaid can create these types of diagram:

  • Flowchart
  • Sequence Diagram
  • Gantt Chart
  • Class Diagram
  • Git Log Graph (experimental)
  • Entity Relationship Diagram (experimental)
  • User Journey Diagram

What Does Notion Have To Do With Mermaid?

Notion recently added Mermaid support to their Code Blocks, you can select it as a language type.

Which means we can add this block to Notion and have the diagram rendered for us:

It supports either showing just the code, showing just the diagram, or showing both together, so you can add some Mermaid code, then choose to just have the diagram appear for conciseness.

Further Reading

Here's some links to learn more about Mermaid diagrams: