DEV Community

nagasuresh dondapati
nagasuresh dondapati

Posted on • Edited on

Mastering Mermaid: A Comprehensive Cheat Sheet

#mermaid #diagramsascode #cheatsheet

Mermaid.js lets you turn plain text into beautiful diagrams—right inside your markdown. In this cheat‑sheet style guide, you’ll learn the core syntax for the most common diagram types so you can start visualizing workflows, data models, and timelines in minutes.

1. Setup & Common Options

At the top of your diagram, you can configure theme and styling:

%%{init: { 
  "theme": "default", 
  "themeVariables": { 
    "primaryColor": "#ffdead" 
  } 
}}%%
Enter fullscreen mode Exit fullscreen mode
  • Wrap your code in a triple‑backtick block labeled mermaid.
  • Configure theme, fonts, colors, and more via the init directive.

2. Flowcharts 

flowchart LR    %% LR = left→right; TB = top→bottom
  A[Start] --> B{Decision?};
  B -- Yes --> C[Action OK];
  B -- No  --> D[Action FAIL];
  C --> E[End];
  D --> E;
Enter fullscreen mode Exit fullscreen mode
  • Node shapes
    • Rectangle: [Label]
    • Rounded: (Label)
    • Circle: ((Label))
    • Diamond (decision): {Label}
  • Arrows
    • Solid: -->
    • Dashed: -.->
    • Bold: ==>
  • Grouping 
  subgraph GroupName
    A
    B
  end
Enter fullscreen mode Exit fullscreen mode

3. Sequence Diagrams 

sequenceDiagram
  participant Alice
  participant Bob
  Alice->>Bob: Hello Bob
  Bob-->>Alice: Hi Alice
  Note right of Bob: Bob thinks…
Enter fullscreen mode Exit fullscreen mode
  • Declare participants with participant Name.
  • Arrow types:
    • ->> solid
    • -->> dashed (reply)
  • Add inline notes: Note left/right of Participant: text

4. Gantt Charts 

gantt
  title Project Timeline
  dateFormat  YYYY-MM-DD
  section Phase 1
    Task A       :a1, 2025-04-01, 10d
    Task B       :after a1, 7d
  section Phase 2
    Milestone    :milestone, 2025-05-01, 0d
Enter fullscreen mode Exit fullscreen mode
  • Use section to group tasks.
  • Specify durations in days Nd, weeks Nw, or relative (after <id>).

5. Class Diagrams 

classDiagram
  class Person {
    +String name
    +int age
    +greet()
  }
  class Student <|-- Person
  Person : +walk()
Enter fullscreen mode Exit fullscreen mode
  • Inheritance: <|--
  • Composition: *--
  • Aggregation: o--
  • Interfaces: <|..

 6. State Diagrams 

stateDiagram-v2
  [*] --> Idle
  Idle --> Running : start
  Running --> Paused : pause
  Paused --> Running : resume
  Paused --> Idle : stop
Enter fullscreen mode Exit fullscreen mode
  • Use [*] for the start state.
  • Label transitions after a colon.

 7. Entity‑Relationship (ER) Diagrams 

erDiagram
  CUSTOMER ||--o{ ORDER    : places
  ORDER    ||--|{ LINE_ITEM: contains
  CUSTOMER {
    string name
    string address
  }
Enter fullscreen mode Exit fullscreen mode
  • Relationship symbols:
    • One‑to‑one: ||--||
    • One‑to‑many: ||--o{
    • Many‑to‑many: }o--o{

8. User Journey Maps 

journey
  title User Onboarding
  section Visit
    Landing Page : 5: Visitor
    Signup Form  : 3: Visitor
  section Engage
    Tutorial      : 4: New User
    First Project : 2: New User
Enter fullscreen mode Exit fullscreen mode
  • Format: Step Label : score : Actor

 9. Pie Charts 

pie
  title Browser Usage
  "Chrome"  : 60
  "Firefox" : 25
  "Edge"    : 15
Enter fullscreen mode Exit fullscreen mode

 10. Git Graphs 

gitGraph
  commit
  branch develop
  commit
  checkout main
  merge develop
  commit
Enter fullscreen mode Exit fullscreen mode

 11. Tips & Tricks

  • Clickable Nodes & Styling 
  A[Google] --> B(Click me)
  click A "https://google.com" "Go to Google"
  style B fill:#f9f,stroke:#333,stroke-width:2px
Enter fullscreen mode Exit fullscreen mode
  • Comments
    • Single‑line: %% comment
    • Multi‑line: %%{ /* comment */ }%%
  • Live Editor: mermaid.live for instant previews.
  • Embedding: Works in GitHub, GitLab, Obsidian, and many CMS tools.

With this cheat‑sheet in hand, you can start embedding diagrams directly into your markdown files and documentation—no drawing tools required. Happy diagramming!

Top comments (2)

Collapse
 
nevodavid profile image
Nevo David •

i think this is pretty sick tbh, but you think more folks actually use diagrams or just skip straight to code and docs every time

Collapse
 
nagasuresh_dondapati_d5df profile image
nagasuresh dondapati •

Diagrams as Code is super helpful, especially when developers are communicating with management or new hires in the team. It gives everyone a shared language and makes it easier to stay aligned. 🙂