Mermaid

Last updated Mar 6, 2025

JavaScript-based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.

Generate images like below with just text:

Making it git and collaboration ready.

A simple example you can see inDAG.

I am a technical author, and I love writing, but I don’t like creating diagrams. I’ve been using Markdown for many, many years, and for a couple of years, all my diagrams have been created based on Mermaid. I love it; not only can I update and maintain images better in my second brain and articles or even in my book by updating them quickly (change a typo or search-replace).

I can also generate an initial Mermaid based on the article I have written. And then add my ideas to it. I recommend it to anyone. I also use  Mermaid Charts to beautify Mermaid if I need to publish somewhere else as an image. Just paste the mermaid and choose the style. PS: For more complex diagrams I have found PlantUML works great too. But I love Mermaid for its simplicity, and it works out of the box on all my websites, too. Reddit

• TD or TB: This declares the flowchart is oriented from top to bottom
• LR: Horizontal

More on About Mermaid.

• Flowchart
• Sequence Diagram
• Class Diagram
• State Diagram
• Entity Relationship Diagram
• User Journey
• Gantt
• Pie Chart
• Quadrant Chart
• Requirement Diagram
• Gitgraph (Git) Diagram
• C4 Diagram 🦺⚠️
• Mindmaps
• Timeline
• Zenuml
• Sankey
• XYChart 🔥
• Block Diagram 🔥
• Other Examples

gantt
    title Gantt Chart with Mermaid
    dateFormat X
    axisFormat %s
    section Apple
    Apple   : 0, 100
    section Bananas
    75   : 0, 75
    section Oranges
    150   : 0, 150

gantt
    title Gantt Chart with Mermaid
    dateFormat X
    axisFormat %s
    Apple   : 0, 100
    Bananas   : 0, 75
    Oranges   : 0, 150

Apparently, Mermaid can also showcase database objects as shown here:

graph TD
    USER(User) -->|uses| VIEW(View)
    VIEW -->|sees| CONTROLLER(Controller)
    CONTROLLER -->|manipulates| MODEL(Model)
    CONTROLLER -->|requests| SEMANTIC(Semantic Layer)
    SEMANTIC -->|applies business logic| MODEL
    MODEL -->|updates| VIEW
    SEMANTIC -->|abstracts data access| VIEW
    MODEL -->|stores data| Database

    Database[(Database)]

Kubernetes

flowchart LR
    A1-->B1[Normal arrow]
    A2---B2[Open link]
    A3-- This is the text! ---B3[Text on open link]
    A4---|This is the text|B4[Alternative text on open link]
    A5-->|text|B5[Arrow with text]
    A6-- text -->B6[Alternative arrow with text]
    A7-.->B7[Dotted arrow]
    A8-. dotted text .->B8[Dotted with text]
    A9==>B9[Thick arrow]
    A10== thick text ==>B10[Thick with text]
    A11~~~B11[Invisible link]

More on Flowcharts Syntax | Mermaid.

I couldn’t bring human on top, rearranging does not help

%%{init: {'theme':'base'}}%%
graph TD

    subgraph "With GenBI"
        H2[👤 Human] -->|"Prompt"| AI[🧠 AI Model]
        AI -->|"Generate"| Preview[🔍 Preview]
        P2 -->|"Iterate"| H2
        Preview -->|"Ship"| P2[🚀 Production]
        Preview -->|"Refine"| H2
    end

This one has it:

%%{init: {'theme':'base'}}%%
graph TD

    subgraph "With GenBI"
        H2[HUMAN]
        AI[AI Model]
        PRE[Preview]
        P2[Production]
        
        H2 -->|Prompt| AI
        AI -->|Generate| PRE
        PRE -->|Ship| P2
        PRE -->|Refine| H2
        P2 -->|Iterate| H2
    end

The difference is

1. Node Declaration vs Flow Declaration

• The second diagram explicitly declares all nodes first, then defines connections separately:

1
2
3
4
5
6

H2[HUMAN] 
AI[AI Model] 
PRE[Preview] 
P2[Production] 

H2 -->|Prompt| AI

• The first diagram combines node declaration with flow in one line:

1

H2[Human] -->|"Prompt"| AI[AI Model]`

• By declaring nodes separately first (second diagram), Mermaid treats them as independent elements that can be positioned more freely
• When nodes are declared within the flow (first diagram), Mermaid tries to optimize the flow direction, which can lead to different automatic positioning

Ah, I understand the issue now. The error occurs because there’s a reference to Core as a direct node in MergeSCD2 --> Core, but Core is actually a subgraph. In Mermaid, you can’t directly connect to a subgraph - you need to connect to nodes within the subgraph.
TypeError: Cannot read properties of undefined (reading ‘x’) · Issue #5064 · mermaid-js/mermaid · GitHub

• Mermaid Chart: Mermaid Prettifier - Mermaid Chart

More powerful seems to be PlantUML, but Mermaid is the standard for Markdown and supported for most web like GitHub, Obsidian, Quartz, etc.

Origin:
References: