FoggyBalrog.MermaidDotNet Documentation

FoggyBalrog.MermaidDotNet is .NET library to generate Mermaid diagrams code.

Note

This documentation applies to the latest published version, excluding pre-releases.

NuGet Version

See the source code on GitHub: FoggyBalrog/MermaidDotNet.

Add the library to your project

Install the FoggyBalrog.MermaidDotNet NuGet package from nuget.org, or download the nupkg file from the latest release on GitHub.

Compatibility

The library targets .NET Standard 2.1, that is notably compatible with .NET Core 3.0 and later, .NET 5.0 and later, and Mono 6.4 and later.

See details on the package frameworks tab on nuget.org or on Microsoft Learn.

Quick Start

Flowchart

string diagram = Mermaid
    .Flowchart()
    .AddNode("N1", out var n1)
    .AddNode("N2", out var n2)
    .AddNode("N3", out var n3)
    .AddLink(n1, n2, "some text")
    .AddLink(n2, n3)
    .Build();

flowchart TB
    id1["N1"]
    id2["N2"]
    id3["N3"]
    id1 -->|"some text"| id2
    id2 --> id3

Read more at flowchart.md.

Sequence diagram

string diagram = Mermaid
    .SequenceDiagram()
    .AddMember("Alice", out var a)
    .AddMember("Bob", out var b)
    .SendMessage(a, b, $"Hello {b.Name}!")
    .SendMessage(b, a, $"Hello {a.Name}!")
    .Build();

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob!
    Bob->>Alice: Hello Alice!

Read more at sequence-diagram.md.

Class diagram

var diagram = Mermaid
    .ClassDiagram()
    .AddClass("Animal", out var animal)
    .AddClass("Dog", out var dog)
    .AddProperty(animal, "int", "Age")
    .AddMethod(animal, null, "Breathe")
    .AddMethod(animal, "void", "Eat", parameters: 
    [
        ("Food", "food")
    ])
    .AddMethod(dog, "Sound", "Bark", parameters: 
    [
        ("int", "times"),
        ("int", "volume")
    ])
    .AddRelationship(animal, dog, RelationshipType.Inheritance, label: "A dog is an animal")
    .Build();

classDiagram
    class Animal {
        +int Age
        +Breathe()
        +Eat(Food food) Energy
    }
    class Dog {
        +Bark(int times, int volume) Sound
    }
    Animal <|-- Dog : A dog is an animal

Read more at class-diagram.md.

State diagram

var diagram = Mermaid
    .StateDiagram()
    .AddState("State 1", out var s1)
    .AddState("State 2", out var s2)
    .AddTransitionFromStart(s1)
    .AddStateTransition(s1, s2)
    .AddTransitionToEnd(s2)
    .Build();

stateDiagram-v2
    s1 : State 1
    s2 : State 2
    [*] --> s1
    s1 --> s2
    s2 --> [*]

Read more at state-diagram.md.

Entity relationship diagram

string diagram = Mermaid
    .EntityRelationshipDiagram()
    .AddEntity("Customer", out var c)
    .AddEntity("Order", out var o)
    .AddEntity("Product", out var p)
    .AddRelationship(Cardinality.ExactlyOne, c, Cardinality.ZeroOrMore, o, "places")
    .AddRelationship(Cardinality.ExactlyOne, o, Cardinality.OneOrMore, p, "contains")
    .Build();

erDiagram
    Customer ||--o{ Order : "places"
    Order ||--|{ Product : "contains"

Read more at entity-relationship-diagram.md.

User journey diagram

var diagram = Mermaid
    .UserJourneyDiagram()
    .AddTask("Task 1", 1, "Actor 1", "Actor 2")
    .AddTask("Task 2", 2)
    .AddSection("Section 1")
    .AddTask("Task 3", 3)
    .AddTask("Task 4", 4, "Actor 3")
    .AddSection("Section 2")
    .AddTask("Task 5", 5, "Actor 1", "Actor 3")
    .AddTask("Task 6", 6, "Actor 2")
    .Build();

journey
    Task 1: 1: Actor 1, Actor 2
    Task 2: 2
    section Section 1
        Task 3: 3
        Task 4: 4: Actor 3
    section Section 2
        Task 5: 5: Actor 1, Actor 3
        Task 6: 6: Actor 2

Read more at user-journey-diagram.md.

Gantt diagram

string diagram = Mermaid
    .GanttDiagram()
    .AddTask("Foo", Date("2024-05-01"), Date("2024-05-05"), out _)
    .AddTask("Bar", Date("2024-05-08"), Date("2024-05-12"), out _)
    .Build();

gantt
    dateFormat YYYY-MM-DD
    Foo: task1, 2024-05-01, 2024-05-05
    Bar: task2, 2024-05-03, 2024-05-08

Read more at gantt-diagram.md.

Git graph

string graph = Mermaid
    .GitGraph()
    .Commit()
    .Branch("dev", out Branch dev)
    .Commit()
    .Checkout(dev)
    .Commit()
    .Commit()
    .CheckoutMain()
    .Commit()
    .Merge(dev)
    .Commit()
    .Build();

gitGraph
    commit
    branch dev
    commit
    checkout dev
    commit
    commit
    checkout main
    commit
    merge dev
    commit

Read more at git-graph.md.

Mind Map

var mindMap = Mermaid
    .MindMap("Root")
    .AddNode("Node 1", out var node1)
    .AddNode("Node 2", out var node2, node1)
    .AddNode("Node 3", out var node3, node1)
    .AddNode("Node 4", out var node4, node2)
    .AddNode("Node 5", out var node5, node2)
    .AddNode("Node 6", out var node6, node3)
    .AddNode("Node 7", out var node7, node3)
    .Build();

mindmap
    Root
        Node 1
            Node 2
                Node 4
                Node 5
            Node 3
                Node 6
                Node 7

Read more at mind-map.md.

Kanban diagram

string diagram = Mermaid
    .KanbanDiagram("some title")
    .AddColumn("foo", x => x
        .AddTask("t1")
        .AddTask("t2", assigned: "Alice", ticket: "JIRA-123", priority: Priority.VeryHigh))
    .AddColumn("bar", x => x
        .AddTask("t3", assigned: "Alice", priority: Priority.VeryHigh)
        .AddTask("t4", ticket: "JIRA-123"))
    .AddColumn("baz")
    .Build();

---
title: some title
---
kanban
    column0[foo]
        task00[t1]
        task01[t2]@{ assigned: 'Alice', ticket: JIRA-123, priority: 'Very High' }
    column1[bar]
        task10[t3]@{ assigned: 'Alice', priority: 'Very High' }
        task11[t4]@{ ticket: JIRA-123 }
    column2[baz]

Read more at kanban-diagram.md.

Packet diagram

string diagram = Mermaid
    .PacketDiagram("some title")
    .AddFieldWithEnd(10, "foo")
    .AddFieldWithBits(5, "bar")
    .AddFieldWithEnd(25, "baz")
    .Build();

---
title: some title
---
packet
0-10: "foo"
+5: "bar"
16-25: "baz"

Read more at packet-diagram.md.

Pie chart

var pieChart = Mermaid
    .PieChart()
    .AddDataSet("Label1", 42.7)
    .AddDataSet("Label2", 57.3)
    .Build();

pie
    "Label1": 42.7
    "Label2": 57.3

Read more at pie-chart.md.

Quadrant chart

var quadrantChart = Mermaid
    .QuadrantChart()
    .AddPoint("A", 0.1, 0.2)
    .AddPoint("B", 0.3, 0.4)
    .Build();

quadrantChart
    A: [0.1, 0.2]
    B: [0.3, 0.4]

Read more at quadrant-chart.md.

Requirement diagram

string diagram = Mermaid
    .RequirementDiagram()
    .AddRequirement("Requirement 1", out var requirement1)
    .AddRequirement("Requirement 2", out var requirement2)
    .AddElement("Element 1", out var element1)
    .AddElement("Element 2", out var element2)
    .AddRelationship(element1, requirement1, RelationshipType.Satisfies)
    .AddRelationship(element2, requirement2, RelationshipType.Satisfies)
    .Build();

requirementDiagram
    requirement "Requirement 1" {
    }
    requirement "Requirement 2" {
    }
    element "Element 1" {
    }
    element "Element 2" {
    }
    "Element 1" - satisfies -> "Requirement 1"
    "Element 2" - satisfies -> "Requirement 2"

Read more at requirement-diagram.md.

Timeline diagram

string diagram = Mermaid
    .TimelineDiagram("Some title")
    .AddEvents("2021", "Event 1", "Event 2")
    .AddEvents("2022", "Event 3")
    .AddEvents("2023", "Event 4", "Event 5", "Event 6")
    .Build();

timeline
    title Some title
    2021 : Event 1 : Event 2
    2022 : Event 3
    2023 : Event 4 : Event 5 : Event 6

Read more at timeline-diagram.md.

Sankey diagram

var diagram = Mermaid
    .SankeyDiagram()
    .AddFlow("A", "B", 30)
    .AddEmptyLine()
    .AddFlow("B", "C", 20)
    .AddFlow("B", "D", 10)
    .Build();

sankey
A,B,30

B,C,20
B,D,10

Read more at sankey-diagram.md.

XY Chart

string diagram = Mermaid
    .XYChart("Some title")
    .WithCategoricalXAxis(["Jan", "Feb", "Mar", "Apr", "May"], "Months")
    .WithNumericYAxis(0, 100, "Percentage")
    .AddBarSeries([20, 40, 60, 80, 100])
    .AddLineSeries([15, 95, 25, 75, 35])
    .Build();

---
title: Some title
---
xychart
x-axis "Months" ["Jan", "Feb", "Mar", "Apr", "May"]
y-axis "Percentage" 0 --> 100
bar [20, 40, 60, 80, 100]
line [15, 95, 25, 75, 35]

Read more at xy-chart.md.

Block Diagram

var diagram = Mermaid
    .BlockDiagram()
    .AddBlock("Frontend", out var frontend)
    .AddSpace()
    .AddBlock("Backend", out var backend)
    .AddSpace()
    .AddBlock("Database", out var database, shape: BlockShape.Cylindrical)
    .AddLink(frontend, backend, "HTTP")
    .AddLink(backend, database, "TCP")
    .Build();

block
    b0["Frontend"]
    space
    b1["Backend"]
    space
    b2[("Database")]
    b0 --"HTTP"--> b1
    b1 --"TCP"--> b2

Read more at block-diagram.md.

Input sanitization

Input sanitization is the process of escaping reserved characters in inputs to prevent syntax errors in the generated Mermaid code. The sanitization rules are based on Mermaid syntax and vary by diagram type and input position.

Sanitization is not a universal escaping layer. It is only applied where Mermaid syntax supports escaped codes, so some inputs still need to avoid reserved characters even when sanitization is enabled.

Input options

Input processing is configured through MermaidDotNetOptions.

Default values:

  • ValidateInputs = true
  • SanitizeInputs = false

Option behavior:

  • ValidateInputs: when true, MermaidDotNet checks inputs against its supported Mermaid rules and throws a MermaidException for invalid values.
  • SanitizeInputs: when true, MermaidDotNet escapes supported inputs before generating Mermaid code. Escaping is diagram-specific and only available where Mermaid syntax supports it.

Option combinations:

ValidateInputs SanitizeInputs Behavior
true false Default mode. Invalid inputs throw exceptions, and valid inputs are emitted as provided.
false false Raw mode. No validation and no sanitization are applied.
false true Supported inputs are sanitized, but no validation is performed.
true true Supported inputs are sanitized first, then validated. Values made valid by sanitization can pass validation, but unsupported Mermaid positions may still reject reserved characters.

Example:

var options = new MermaidDotNetOptions
{
    ValidateInputs = false,
    SanitizeInputs = true
};

string diagram = Mermaid
    .Flowchart(options: options)
    .AddNode("N1", out var n1)
    .AddNode("N2", out var n2)
    .AddNode("N3", out var n3)
    .AddLink(n1, n2, "some text")
    .AddLink(n2, n3)
    .Build();

License

This project is licensed under the MIT License. See the LICENSE file for details.

Credits

Mermaid icon created by Smashicons on Flaticon.