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)

mermaid-diagramming

Mermaid Diagramming in Obsidian

⚠️ Obsidian-Specific Constraints

Diagram Selection Guide

Quick Start Examples

Flowchart

Sequence Diagram

Class Diagram

Gantt Chart

State Diagram

Gitgraph

Mindmap

Pie Chart

ER Diagram

User Journey

Timeline

Quadrant Chart

Sankey Diagram

XY Chart

Block Diagram

Architecture Diagram

Common Patterns

Adding Styles

Using Classes

Comments

Reference