This course is a complete, hands-on introduction toMermaid— the JavaScript library that turns markdown-like text into diagrams. You will learn to stop drawing diagrams and startwritingthem.

What you will learn

• Module 1— the foundations: what Mermaid is, why "diagrams as code" matters, and how the pipeline works.
• Module 2— flowcharts: nodes, edges, decisions, and subgraphs.
• Module 3— sequence diagrams: participants, messages, and activation.
• Module 4— Gantt diagrams: timelines, sections, and dependencies.
• Module 5— data models: ER and class diagrams.
• Module 6— state diagrams, pie, mindmap, timeline, and more types.
• Module 7— integration & practice: theming, CLI, best practices.
• Module 8— wrap-up with a final exam.

How to use this course

Each module ends with a short knowledge check. The final exam unlocks your certificate. You can navigate with the arrow keys or the prev/next buttons, and mark pages as done as you go.

Tip:Mermaid is a fast-moving project. Where a version number or star count is cited, it reflects the state at the time of writing (2026). Always check the official docs for the current state.

Mermaid is aJavaScript librarythat turns markdown-like text into diagrams. You write a few lines describing nodes and edges, and Mermaid renders a flowchart, sequence diagram, Gantt chart, class diagram, entity-relationship diagram, pie chart, mind map, or state diagram asSVG.

The source is plain text

Because the source is text, it can be diffed in Git, reviewed in pull requests, and rendered natively in GitHub, GitLab, Notion, Obsidian, and dozens of other tools.

The key numbers

• Created:2014 by Knut Sveidqvist, a Swedish software architect.
• License:MIT — free and open source.
• Scope:15+ diagram types (flowchart, sequence, gantt, class, er, pie, mindmap …).
• Adoption:over 90,000 GitHub stars (as of 2026).

A minimal example

flowchart LR
  A[Write text] --> B[Parse] --> C[Render SVG]

LRmeans "left to right",TDmeans "top down".[text]is a rectangle node,-->is an arrow.

Fun Fact:The name comes from "The Little Mermaid" — the Disney film Knut Sveidqvist's children were watching when he started the project in 2014.

The failure mode Mermaid kills isdoc-rot. A diagram you draw in Visio or draw.io is a binary blob: it cannot be diffed, it drifts from the code it describes, and it dies with the person who owns the file.

The origin story

Knut Sveidqvist lost a Microsoft Visio file in 2014 and realized: the fix was not a better editor, but abandoning binary diagram files in favor oftext. If a diagram were text, it could live in version control, diff cleanly, and stay in sync with the code.

The core idea

Text is the most durable, diffable, and reviewable format we have. A Mermaid diagram is a few lines of markdown-like syntax that describe structure — and the renderer turns that into SVG. Because the source is text, it participates in the same workflows as code: pull requests, code review, git blame, CI.

What this means

• Diagrams live in the same repository as the code.
• They are reviewed in the same pull request.
• They change in the same commit.
• When the architecture changes, the diagram changes with it — or the review catches it.

The whole bet:diagrams as code, not as artifacts.

Every Mermaid diagram runs the same pipeline. Understanding this pipeline helps you debug issues and understand why the same source renders consistently everywhere.

The steps

1. Lexer & Parser— the source text is turned into an abstract syntax tree (AST) of the diagram: nodes, edges, and their attributes.
2. Layout engine— positions the elements. Flowcharts use a layered graph layout, sequence diagrams stack participants and messages, Gantt charts map tasks onto a time axis.
3. Serialization— the positioned elements are serialized to SVG.
4. Output— the SVG is rendered in the browser, docs, or chat.

Why it renders everywhere

Mermaid is a single JavaScript library that runs in any browser and can also produce static SVG server-side. That is why GitHub, GitLab, Notion, and Obsidian all support it: they each embed the same renderer.

Layout is computed

Because the layout is computed, you describestructureand Mermaid decides thegeometry. That is why the same source renders consistently everywhere — and why Mermaid is not meant for pixel-perfect layout.

Warning:Mermaid is not a general drawing tool. It shines for structured diagrams (flow, sequence, state, data) and is the wrong tool for free-form illustration or pixel-perfect layout.

Answer the following questions to test your understanding of the foundations.

Flowcharts are the most common diagram type in Mermaid. They model directed graphs with nodes, edges, subgraphs, and decision diamonds.

Basic syntax

flowchart LR
  A[Write text] --> B[Parse] --> C[Render SVG]

• flowchart— the diagram type.
• LR— direction: left to right. Alternatives:TD/TB(top down),RL,BT.
• A[Text]— a rectangle node with IDA.
• -->— an arrow (directed edge).

Node shapes

• A[Text]— rectangle (default).
• A(Text)— rounded rectangle.
• A{Text}— diamond (decision).
• A((Text))— circle.
• A>Text]— asymmetric shape.

Edge types

• -->— solid arrow.
• ---— solid line without arrow.
• -.->— dotted arrow.
• ==>— thick arrow.

Remember:LR= left to right,TD= top down.[text]is a rectangle node,-->is an arrow.

Most flowcharts you will ever write take the form of a decision flow.

Decision diamond

flowchart TD
  A[Start] --> B{Is it a diagram?}
  B -- yes --> C[Write Mermaid text]
  B -- no --> D[Write prose]
  C --> E[Render] --> F[Commit to Git] --> G[Ship docs]

• {}makes a diamond.
• -- yes -->labels the edge.

Subgraphs

Subgraphs group nodes inside a frame:

flowchart LR
  subgraph Backend
    A[API] --> B[Database]
  end
  subgraph Frontend
    C[UI] --> D[Client]
  end
  D --> A

subgraph Name...endcreates a group. You can also give subgraphs an ID:subgraph id[Display name].

Labeled edges

A -- Text --> B
A -->|Text| B

Both forms label an edge.

Remember:{}makes a diamond,-- Text -->labels an edge, andsubgraph ... endgroups nodes.

Test your understanding of flowchart syntax.

Sequence diagrams modelwho talks to whom, in the right order. They are ideal for message passing between participants.

Basic syntax

sequenceDiagram
  participant U as User
  participant B as Browser
  participant M as Mermaid
  U->>B: open page
  B->>M: render("flowchart", src)
  M-->>B: SVG string
  B-->>U: draw diagram

Participants

• participant U— defines a participant with IDU.
• participant U as User— renames the actor (display name).

Message types

• ->— solid line without arrow.
• -->— dotted line without arrow.
• ->>— solid arrow (call).
• -->>— dotted arrow (reply).
• -x— solid line with cross (loss).

Remember:->>is a solid arrow,-->>a dotted reply.participant X as Labelrenames the actor.

Sequence diagrams can show activation bars and notes to model flows more precisely.

Activation

sequenceDiagram
  participant A as Client
  participant S as Server
  A->>+S: send request
  S-->>-A: response
  A->>A: process locally

• +after the arrow opens an activation bar.
• -after the arrow closes it.
• A->A— a self-message (participant talks to itself).

Notes

sequenceDiagram
  participant A
  participant B
  Note left of A: left of A
  Note right of A: right of A
  Note over A,B: over both

• Note left of A— note left of A.
• Note right of A— note right of A.
• Note over A,B— note over A and B.

Loops and Alternatives

sequenceDiagram
  participant C as Client
  participant S as Server
  loop Each attempt
    C->>S: Request
    alt Success
      S-->>C: 200 OK
    else Error
      S-->>C: 500 Error
    end
  end

loop ... endcreates a loop,alt ... else ... endan alternative.

Remember:+/-control activation bars,Noteadds notes,loopandaltmodel loops and alternatives.

Test your understanding of sequence diagram syntax.

Gantt charts lay tasks out over time. They are ideal for project planning and deadline overviews.

Basic syntax

gantt
  title Project Timeline
  dateFormat YYYY-MM-DD
  section Build
  Frontend :b1, 2026-09-10, 10d
  Backend :b2, 2026-09-10, 12d
  section Ship
  QA :c1, 2026-09-22, 5d
  Launch :c2, after c1, 2d

The elements

• title— the chart title.
• dateFormat— the date format (e.g.YYYY-MM-DD).
• section— groups tasks into sections.
• :id, start, duration— defines each bar.
• after c1— links dependencies (task starts after c1).

Duration units

• 10d— 10 days.
• 2w— 2 weeks.
• 3h— 3 hours.
• after c1— relative to another task.

Remember:sectiongroups tasks,:id, start, durationdefines each bar, andafter c1links dependencies.

Gantt charts are structured with sections and dependencies.

Sections

Sections group related tasks and produce color-separated bars:

gantt
  title Release Plan
  dateFormat YYYY-MM-DD
  section Design
  Concept :a1, 2026-10-01, 5d
  Prototype :a2, after a1, 7d
  section Development
  Backend :b1, after a2, 14d
  Frontend :b2, after a2, 12d
  section Delivery
  QA :c1, after b1, 5d
  Release :c2, after c1, 2d

Dependencies

Withafter <id>you specify that a task starts only after another is complete. This creates a chain of dependencies.

Milestones

gantt
  dateFormat YYYY-MM-DD
  section Milestones
  Kickoff :milestone, m1, 2026-10-01, 0d

A milestone is a task with duration0dand the keywordmilestone.

Remember:Sections group tasks,aftercreates dependencies, andmilestonewith duration0dmarks a milestone.

Test your understanding of Gantt syntax.

ER diagrams model data: entities, attributes, and cardinality. They are ideal for data models.

Basic syntax

erDiagram
  USER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  USER {
    int id PK
    string name
    string email
  }

Cardinality

• ||--o{— "one to many" (optional).
• ||--|{— "one to exactly many".
• }o--||— "many to one".
• ||--||— "one to one".

Attributes

Fields go inside the entity block with type and markers:

USER {
  int id PK
  string name
  string email
}

• PK— primary key.
• FK— foreign key.
• UK— unique key.

Remember:||--o{reads as "one to many",||--|{as "one to exactly many". Fields go inside the entity block withPK/FKmarkers.

Class diagrams model classes, inheritance, composition, and relationships — ideal for object-oriented architecture.

Basic syntax

classDiagram
  class Diagram {
    +render() SVG
    +parse() AST
  }
  class Flowchart
  class Sequence
  class Gantt
  Diagram <|-- Flowchart
  Diagram <|-- Sequence
  Diagram <|-- Gantt

Relationships

• <|--— inheritance ("is a").
• *--— composition.
• o--— aggregation.
• --— association.
• ..>— dependency.

Visibility

• +— public.
• -— private.
• #— protected.

Methods and attributes

classDiagram
  class Car {
    -string brand
    +drive() void
    +getBrand() string
  }

Remember:<|--means inheritance,*--composition,o--aggregation.+is public,-private,#protected.

Test your understanding of ER and class diagrams.

State diagrams model finite-state machines with transitions and guards. They are ideal for workflows and lifecycles.

Basic syntax

stateDiagram-v2
  [*] --> Draft
  Draft --> Review
  Review --> Approved
  Review --> Draft : Rejection
  Approved --> Published
  Published --> Archived
  Archived --> [*]

The elements

• [*]— start and end state.
• Draft— a state.
• -->— a transition.
• : Rejection— labels the transition (guard/label).

States with description

stateDiagram-v2
  state "In Review" as Review
  [*] --> Review
  Review --> [*]

state "Display name" as iddefines a state with a display name and ID.

Composite states

stateDiagram-v2
  state "Publication" as Pub {
    [*] --> Draft
    Draft --> Published
  }

Composite states group substates in one block.

Remember:[*]is start/end,-->a transition,: Labellabels the transition.

Mermaid offers many more diagram types. Here are the main ones.

Pie chart

pie title Diagram types in docs
  "Flowcharts" : 45
  "Sequence diagrams" : 20
  "Gantt" : 15
  "ER" : 10
  "Other" : 10

piecreates a pie chart fromlabel : valuepairs.

Mindmap

mindmap
  root((Mermaid))
    Flowchart
    Sequence diagram
    Gantt
    ER
    State
    Pie

mindmapcreates a hierarchical mindmap from indented text.

Timeline

timeline
  title Project progress
  2026 Q1 : Concept
  2026 Q2 : Development
  2026 Q3 : QA
  2026 Q4 : Release

timelineshows chronological events with sections.

More types

• journey— user journey diagram with task points.
• gitGraph— Git commit/branch/merge history.
• quadrantChart— points in four quadrants.
• requirementDiagram— requirements and their relationships.
• C4Context— C4 architecture context diagrams.
• sankey— flow magnitude between nodes.

Remember:pieuseslabel : valuepairs,mindmapindented text,timelinechronological events.

Test your understanding of state diagrams and other types.

Mermaid supports themes and theme variables so diagrams can match a brand or a website.

Themes

%%{init: {"theme": "dark"}}%%
flowchart LR
  A[Start] --> B[End]

With%%{init: {...}}%%you can set configuration. Available themes:default,dark,forest,neutral,base.

Theme variables

%%{init: {"theme": "base", "themeVariables": {
  "primaryColor": "#0F1A16",
  "primaryTextColor": "#E8F2EA",
  "lineColor": "#22D3EE"
}}}%%

Theme variables control colors for the background, text, edges, and more.

Inline styling of individual nodes

flowchart LR
  A[Important] --> B[Normal]
  style A fill:#0F1A16,stroke:#4ADE80

style A fill:#0F1A16,stroke:#4ADE80styles a single node inline.

Remember:%%{init: {...}}%%sets configuration,themeVariablescontrols colors, andstyle A fill:...,stroke:...styles single nodes.

Mermaid can be integrated into many tools and rendered server-side to SVG.

Native support

Mermaid renders natively in:

• GitHub— in Markdown code blocks.
• GitLab— also native.
• Notion— via Mermaid blocks.
• Obsidian— via Mermaid code blocks.

Server-side rendering

For static websites you can pre-render Mermaid to SVG at build time. That makes diagrams simple files — fast to load, cacheable, and themeable.

CI integration

You can use Mermaid in CI to fail a build when a diagram is malformed. This prevents broken diagrams from reaching the docs.

The live editor

The fastest way to learn is the live editor atmermaid.live— type on the left, see the SVG on the right, copy the source into your docs. No install, no setup, instant feedback.

Remember:Mermaid renders natively in GitHub, GitLab, Notion, and Obsidian. For static sites, pre-render to SVG at build time. Use mermaid.live to sketch.

Here are the most important practices to use Mermaid effectively and avoid common errors.

Best practices

1. Start at mermaid.live— type on the left, see the SVG on the right, copy the source into your docs.
2. Learn the four that cover most needs:flowchart, sequenceDiagram, gantt, and erDiagram.
3. Keep diagrams in the same repo as the code, so they change in the same commit.
4. Pre-render to SVG at build time for static sites— fast, cacheable, themeable.
5. Use the live editor to sketch, then commit the source so it diffs and reviews like code.

Common errors

• Syntax errors fail silently— in some renderers there's no error until you look closely.
• Complex diagrams get cramped— the layout is automatic, not hand-tuned.
• Very large diagrams render slowly— keep them small and focused.

Pros & Cons

Pros:Text source diffs in Git, renders natively in many tools, 15+ diagram types from a small syntax, MIT-licensed, themeable.

Cons:Not a general drawing tool, automatic layout, syntax errors sometimes fail silently, large diagrams can be slow.

Remember:Keep diagrams small, focused, and in the same repo as the code. Use the live editor to sketch.

Test your understanding of theming, integration, and best practices.

You now have the complete picture of Mermaid — diagrams as code.

Key takeaways

• Mermaidis a JavaScript library that turns markdown-like text into SVG diagrams.
• Diagrams as codemeans: a text source that diffs in Git, is reviewed in pull requests, and stays in sync with the code.
• The pipeline:text → Lexer/Parser → AST → Layout engine → SVG.
• Flowchartsmodel directed graphs with nodes, edges, decisions, and subgraphs.
• Sequence diagramsmodel message passing between participants.
• Gantt chartslay tasks out over time.
• ER and class diagramsmodel data and object structures.
• State diagrams, pie, mindmap, timelineand more types cover many use cases.
• Theming and integrationmake Mermaid customizable and usable everywhere.

The takeaways

1. Start at mermaid.live.
2. Learn the four: flowchart, sequenceDiagram, gantt, erDiagram.
3. Keep diagrams in the same repo as the code.
4. Pre-render to SVG at build time for static sites.
5. Use the live editor to sketch, then commit the source.

Closing thought:The most valuable skill you can take from this course is not memorizing Mermaid commands — it is understandingwhydiagrams as code matter. That understanding transfers to any tool you use next.

Answer all 25 questions to unlock your certificate. You need at least 70% (18 of 25) to pass. The exam covers all diagram types and features of the course.