Mermaid Diagramming in Obsidian

Obsidian has built-in Mermaid support. Use fenced code blocks with mermaid language identifier.

For common syntax (styling, comments, themes), see reference.md.

⚠️ Obsidian-Specific Constraints

Rendering Differences: Obsidian's Mermaid version may lag behind mermaid.js releases. Some cutting-edge features may not work.

Theme Interaction: Diagram colors adapt to Obsidian theme. Use explicit styles for consistent appearance across themes.

Performance: Very large diagrams (50+ nodes) may slow down rendering. Split into multiple diagrams if needed.

Export: PDF export converts diagrams to images. For external sharing, capture as PNG/SVG.

No JavaScript: Click events and JavaScript callbacks are disabled for security.

---

Diagram Selection Guide

Use Case	Diagram Type	Keyword
Process flow, decision trees	Flowchart	flowchart
API calls, message passing	Sequence	sequenceDiagram
OOP design, relationships	Class	classDiagram
Project timeline, scheduling	Gantt	gantt
State machine, lifecycle	State	stateDiagram-v2
Git branching strategy	Gitgraph	gitGraph
Brainstorming, hierarchies	Mindmap	mindmap
Proportions, percentages	Pie Chart	pie
Database schema, entities	ER Diagram	erDiagram
User experience steps, satisfaction	User Journey	journey
Historical events, milestones	Timeline	timeline
Priority matrix, 2D positioning	Quadrant Chart	quadrantChart
Flow visualization, proportional bands	Sankey Diagram	sankey-beta
Numerical data visualization	XY Chart	xychart-beta
Precise element positioning, layouts	Block Diagram	block-beta
Cloud services, service relationships	Architecture	architecture-beta

---

Quick Start Examples

Flowchart

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Key syntax:

• Direction: TD (top-down), LR (left-right), BT, RL
• Shapes: [rect], (rounded), {diamond}, [(cylinder)], ((circle))
• Arrows: -->, -.-> (dotted), ==> (thick)
• Labels: -->|text| or -- text -->

For details: flowchart.md

---

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant S as Server
    participant D as Database

    C->>S: HTTP Request
    activate S
    S->>D: Query
    D-->>S: Result
    S-->>C: Response
    deactivate S

Key syntax:

• Arrows: ->> (sync), -->> (response), -) (async)
• Activation: activate/deactivate or +/- suffix
• Control: loop, alt/else, opt, par/and, critical
• Notes: Note right of A: text, Note over A,B: text

For details: sequence.md

---

Class Diagram

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +fetch() void
    }
    Animal <|-- Dog : extends

Key syntax:

• Visibility: + public, - private, # protected, ~ package
• Relations: <|-- inheritance, *-- composition, o-- aggregation, --> association
• Methods: +method(args) returnType

For details: class-diagram.md

---

Gantt Chart

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD

    section Planning
    Requirements    :a1, 2024-01-01, 7d
    Design          :a2, after a1, 5d

    section Development
    Implementation  :2024-01-15, 14d
    Testing         :7d

Key syntax:

• dateFormat: Date format (YYYY-MM-DD, etc.)
• Tasks: name :id, start, duration or name :after id, duration
• Modifiers: done, active, crit, milestone

For details: gantt.md

---

State Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : start
    Processing --> Success : complete
    Processing --> Error : fail
    Success --> [*]
    Error --> Idle : retry

Key syntax:

• Start/End: [*]
• Transition: State1 --> State2 : event
• Composite: state Name { ... }
• Fork/Join: state fork_name <<fork>>, <<join>>

For details: state.md

---

Gitgraph

gitGraph
    commit id: "init"
    branch develop
    checkout develop
    commit id: "feat-1"
    commit id: "feat-2"
    checkout main
    merge develop id: "v1.0" tag: "release"

Key syntax:

• commit: Add commit, optional id:, tag:, type:
• branch name: Create branch
• checkout name: Switch branch
• merge name: Merge branch

For details: gitgraph.md

---

Mindmap

mindmap
    root((Project))
        Frontend
            React
            TypeScript
        Backend
            Node.js
            PostgreSQL
        DevOps
            Docker
            CI/CD

Key syntax:

• Indentation defines hierarchy
• Shapes: root((circle)), (rounded), [square], ))cloud((
• Use 4-space or tab indentation

For details: mindmap.md

---

Pie Chart

pie showData
    title Browser Market Share
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 8
    "Edge" : 5
    "Other" : 3

Key syntax:

• title: Optional chart title
• showData: Display values on segments
• Format: "Label" : value

For details: pie.md

---

ER Diagram

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER {
        int id PK
        string email UK
        string name
    }

Key syntax:

• Entities: ENTITY_NAME
• Attributes: type name [PK/FK/UK]
• Cardinality: ||--o{ (one to many), ||--|| (one to one)
• Relationship: ENTITY1 REL ENTITY2 : label

For details: er-diagram.md

---

User Journey

journey
    title Customer Support
    section Contact
      Submit ticket: 2: Customer
      Receive notice: 4: Agent
    section Resolution
      Troubleshoot issue: 3: Agent
      Confirm solution: 5: Customer

Key syntax:

• Sections: section name
• Tasks: Task name: score: actor
• Score: 1-5 (1 = unsatisfied, 5 = satisfied)
• Actors: User roles involved

For details: journey.md

---

Timeline

timeline
    title Product Roadmap
    section 2023
        Q1 2023 : MVP launch
        Q4 2023 : v1.0 release
    section 2024
        Q2 2024 : Major features
        Q4 2024 : v2.0

Key syntax:

• Time periods: period : event
• Sections: Group related periods
• Multiple events: period : event1 : event2
• Flexible format: Years, months, quarters, or custom text

For details: timeline.md

---

Quadrant Chart

quadrantChart
    title Feature Prioritization
    x-axis Effort --> Value
    y-axis Complexity --> Impact
    Dark Mode: [0.4, 0.7]
    Search: [0.6, 0.8]
    Export PDF: [0.7, 0.6]
    Fix UI Bug: [0.2, 0.3]

Key syntax:

• Axes: x-axis label --> label and y-axis label --> label
• Points: Name: [x, y] (coordinates 0.0-1.0)
• Quadrants: Auto-divided at 0.5 on both axes

For details: quadrant-chart.md

---

Sankey Diagram

sankey-beta

A,B,10
A,C,15
B,D,8
C,D,22

Key syntax:

• CSV format: source, target, value
• Three columns required
• Values are numeric (flow magnitude)
• Nodes auto-created from sources/targets

For details: sankey.md

---

XY Chart

xychart-beta
    title "Sales Data"
    x-axis [Jan, Feb, Mar, Apr, May]
    y-axis "Revenue" 0 --> 100
    line [30, 45, 55, 70, 85]

Key syntax:

• Chart type: xychart-beta or xychart-beta horizontal
• X-axis: [categories] or min --> max
• Y-axis: "label" min --> max
• Series: line [values] or bar [values]

For details: xychart.md

---

Block Diagram

block-beta
    columns 2
    A["Frontend"]:1
    B["Backend"]:1
    C["Database"]:2

    style A fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style B fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    style C fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20

Key syntax:

• Blocks: ID["Label"]:SPAN - Each block on new line
• Columns: columns N - Define layout width
• Styling: style ID fill:#hex,stroke:#hex,color:#hex
• Spans: :N suffix - How many columns block occupies

For details: block.md

---

Architecture Diagram

architecture-beta
    group Cloud(cloud)[Cloud Infrastructure]
    service web(server)[Web Server] in Cloud
    service api(server)[API Server] in Cloud
    service db(database)[Database]

    web:R --> L:api
    api:R --> L:db

Key syntax:

• Groups: group {id}({icon})[{label}] - Organize services
• Services: service {id}({icon})[{label}] (in {parent})? - Available icons: server, database, cloud, disk, internet
• Nesting: in {parent_id} - Place service/group inside parent group
• Connections: {id1}:{pos} {arrow} {pos}:{id2} - Position: L(eft), R(ight), T(op), B(ottom)
• Arrows: --> (right), <-- (left), -- (both)

For details: architecture.md

---

Common Patterns

Adding Styles

flowchart LR
    A[Normal] --> B[Styled]
    style B fill:#f96,stroke:#333,stroke-width:2px

Using Classes

flowchart LR
    A:::highlight --> B --> C:::highlight
    classDef highlight fill:#ff0,stroke:#f00,stroke-width:2px

Comments

flowchart TD
    %% This is a comment
    A --> B

---

Reference

For complete documentation on common features:

• reference.md - Styling, themes, comments, directives

For diagram-specific guides:

• flowchart.md - Node shapes, links, subgraphs
• sequence.md - Messages, activation, control flow
• class-diagram.md - Classes, relationships
• gantt.md - Tasks, dependencies, milestones
• state.md - States, transitions, composite states
• gitgraph.md - Commits, branches, merges
• mindmap.md - Hierarchies, node shapes
• pie.md - Proportional data
• er-diagram.md - Entities, attributes, relationships (Session 1)
• journey.md - User journeys, satisfaction scores (Session 1)
• timeline.md - Events, milestones, time periods (Session 1)
• quadrant-chart.md - Priority matrix, 2D positioning (Session 2)
• sankey.md - Flow visualization, proportional bands (Session 2)
• xychart.md - Numerical data visualization (Session 2)
• block.md - Element positioning, multi-column layouts (Session 3)
• architecture.md - Cloud services, service relationships (Session 3)