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. 🙂