Mermaid Diagrams in mdsvr

mdsvr supports Mermaid.js for creating beautiful diagrams directly in your Markdown files. Simply wrap your Mermaid code in triple backticks with the mermaid language identifier, and mdsvr will render it as an interactive diagram.

Quick Start


  

    
    
    
  

  

    
    
  

  

    
flowchart LR
    A[Write Markdown] --> B[Add Mermaid Code]
    B --> C[mdsvr Renders]
    C --> D[Beautiful Diagram]

  

  
flowchart LR
    A[Write Markdown] --> B[Add Mermaid Code]
    B --> C[mdsvr Renders]
    C --> D[Beautiful Diagram]

Syntax: All Mermaid diagrams start with a diagram type keyword, followed by the content.


  

    
    
    
  

  

    
    
  

  

    
flowchart TD
    A[Diagram Type] --> B[Content]
    B --> C[End]

  

  
flowchart TD
    A[Diagram Type] --> B[Content]
    B --> C[End]

Comments: Use %% to add comments that won’t be rendered.

Supported Diagram Types

mdsvr supports all 19 Mermaid diagram types. Below is a complete showcase with practical examples.

1. Flowchart

Best for: Process flows, workflows, decision trees, algorithms.

Example: User Authentication Flow


  

    
    
    
  

  

    
    
  

  

    
flowchart TD
    A["User visits site"] --> B{"Logged in?"}
    B -->|"Yes"| C["Show dashboard"]
    B -->|"No"| D["Show login form"]
    D --> E{"Valid credentials?"}
    E -->|"Yes"| F["Create session"]
    E -->|"No"| G["Show error"]
    F --> C
    G --> D

    subgraph Auth["Authentication System"]
        D
        E
        F
        G
    end

  

  
flowchart TD
    A["User visits site"] --> B{"Logged in?"}
    B -->|"Yes"| C["Show dashboard"]
    B -->|"No"| D["Show login form"]
    D --> E{"Valid credentials?"}
    E -->|"Yes"| F["Create session"]
    E -->|"No"| G["Show error"]
    F --> C
    G --> D

    subgraph Auth["Authentication System"]
        D
        E
        F
        G
    end

Syntax Guide

Directions: TD (top-down), LR (left-right), BT (bottom-up), RL (right-left)

Node shapes:

  • A["Text"] - Rectangle
  • B("Text") - Rounded
  • C{"Text"} - Diamond (decision)
  • D(("Text")) - Circle
  • E(["Text"]) - Stadium

Arrows: --> (arrow), --- (line), -.-> (dotted), ==> (thick)

Labels: A -->|"label"| B

2. Sequence Diagram

Best for: API documentation, authentication flows, message exchanges between systems.

Example: API Authentication Flow


  

    
    
    
  

  

    
    
  

  

    
sequenceDiagram
    participant User
    participant Browser
    participant API as "API Server"
    participant DB as "Database"

    User->>Browser: Enter credentials
    Browser->>+API: POST /auth/login
    API->>+DB: Query user
    DB-->>-API: User data
    alt Valid credentials
        API-->>-Browser: JWT token
        Browser-->>User: Redirect to dashboard
    else Invalid
        API-->>Browser: 401 error
        Browser-->>User: Show error message
    end

  

  
sequenceDiagram
    participant User
    participant Browser
    participant API as "API Server"
    participant DB as "Database"

    User->>Browser: Enter credentials
    Browser->>+API: POST /auth/login
    API->>+DB: Query user
    DB-->>-API: User data
    alt Valid credentials
        API-->>-Browser: JWT token
        Browser-->>User: Redirect to dashboard
    else Invalid
        API-->>Browser: 401 error
        Browser-->>User: Show error message
    end

Syntax Guide

Participants: participant Name as "Display Name"

Arrows:

  • ->> - Solid (request)
  • -->> - Dashed (response)
  • ->>+ - Activate
  • -->>- - Deactivate

Blocks: loop, alt/else, opt, par/and, critical

3. Class Diagram

Best for: Software architecture, OOP structure, data models.

Example: E-commerce System


  

    
    
    
  

  

    
    
  

  

    
classDiagram
    class User {
        +int id
        +string email
        +string name
        +login() bool
        +logout() void
    }

    class Order {
        +int id
        +float total
        +string status
        +addItem() void
        +checkout() void
    }

    class Product {
        +int id
        +string name
        +float price
        +int stock
    }

    User "1" --> "*" Order : places
    Order "*" --> "*" Product : contains

  

  
classDiagram
    class User {
        +int id
        +string email
        +string name
        +login() bool
        +logout() void
    }

    class Order {
        +int id
        +float total
        +string status
        +addItem() void
        +checkout() void
    }

    class Product {
        +int id
        +string name
        +float price
        +int stock
    }

    User "1" --> "*" Order : places
    Order "*" --> "*" Product : contains

Syntax Guide

Visibility: + (public), - (private), # (protected), ~ (package)

Relationships:

  • <|-- - Inheritance
  • *-- - Composition
  • o-- - Aggregation
  • --> - Association

Cardinality: "1", "0..1", "*", "1..*"

4. State Diagram

Best for: State machines, lifecycles, process states.

Example: Document Lifecycle


  

    
    
    
  

  

    
    
  

  

    
stateDiagram-v2
    [*] --> Draft
    Draft --> Review : Submit
    Review --> Published : Approve
    Review --> Draft : Reject
    Published --> Archived : Archive
    Archived --> [*]

    state Review {
        [*] --> Pending
        Pending --> Approved
        Pending --> Rejected
    }

  

  
stateDiagram-v2
    [*] --> Draft
    Draft --> Review : Submit
    Review --> Published : Approve
    Review --> Draft : Reject
    Published --> Archived : Archive
    Archived --> [*]

    state Review {
        [*] --> Pending
        Pending --> Approved
        Pending --> Rejected
    }

5. ER Diagram

Best for: Database schemas, data modeling.

Example: Blog Database Schema


  

    
    
    
  

  

    
    
  

  

    
erDiagram
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    POST {
        int id PK
        int user_id FK
        string title
        text content
        string status
    }

    COMMENT {
        int id PK
        int post_id FK
        int user_id FK
        text body
    }

    USER ||--o{ POST : writes
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes

  

  
erDiagram
    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    POST {
        int id PK
        int user_id FK
        string title
        text content
        string status
    }

    COMMENT {
        int id PK
        int post_id FK
        int user_id FK
        text body
    }

    USER ||--o{ POST : writes
    POST ||--o{ COMMENT : has
    USER ||--o{ COMMENT : writes

Syntax Guide

Relationships:

  • ||--|| - One to one
  • ||--o{ - One to zero or more
  • ||--|{ - One to one or more
  • }o--o{ - Zero or more to zero or more

Keys: PK (primary), FK (foreign), UK (unique)

6. Gantt Chart

Best for: Project planning, timelines, sprint schedules.

Example: Project Timeline


  

    
    
    
  

  

    
    
  

  

    
gantt
    title Website Development
    dateFormat YYYY-MM-DD
    excludes weekends

    section Planning
        Requirements :done, p1, 2024-01-01, 5d
        Design :done, p2, after p1, 7d

    section Development
        Backend :active, dev1, after p2, 14d
        Frontend :crit, dev2, after p2, 14d

    section Launch
        Testing :test, after dev1, 7d
        Deploy :milestone, deploy, after test, 1d

  

  
gantt
    title Website Development
    dateFormat YYYY-MM-DD
    excludes weekends

    section Planning
        Requirements :done, p1, 2024-01-01, 5d
        Design :done, p2, after p1, 7d

    section Development
        Backend :active, dev1, after p2, 14d
        Frontend :crit, dev2, after p2, 14d

    section Launch
        Testing :test, after dev1, 7d
        Deploy :milestone, deploy, after test, 1d

Syntax Guide

Status: done, active, crit (critical), milestone

Duration: 5d (days), 2w (weeks), after task_id

7. User Journey

Best for: UX design, customer experience mapping.

Example: E-commerce Checkout


  

    
    
    
  

  

    
    
  

  

    
journey
    title Shopping Experience
    section Discovery
        Search products: 5: Customer
        View product details: 4: Customer
    section Purchase
        Add to cart: 5: Customer
        Checkout process: 3: Customer
        Payment: 4: Customer
    section Post-purchase
        Order confirmation: 5: Customer
        Delivery tracking: 4: Customer

  

  
journey
    title Shopping Experience
    section Discovery
        Search products: 5: Customer
        View product details: 4: Customer
    section Purchase
        Add to cart: 5: Customer
        Checkout process: 3: Customer
        Payment: 4: Customer
    section Post-purchase
        Order confirmation: 5: Customer
        Delivery tracking: 4: Customer

Syntax Guide

Score: 1 (very bad) to 5 (very good)

Format: Step name: score: Actor

8. Git Graph

Best for: Visualizing Git workflows, branching strategies.

Example: Feature Branch Workflow


  

    
    
    
  

  

    
    
  

  

    
gitGraph
    commit id: "init"
    branch develop
    checkout develop
    commit id: "feat-a"
    commit id: "feat-b"
    branch feature/auth
    checkout feature/auth
    commit id: "login"
    commit id: "register"
    checkout develop
    merge feature/auth
    checkout main
    merge develop tag: "v1.0"
    commit id: "hotfix"

  

  
gitGraph
    commit id: "init"
    branch develop
    checkout develop
    commit id: "feat-a"
    commit id: "feat-b"
    branch feature/auth
    checkout feature/auth
    commit id: "login"
    commit id: "register"
    checkout develop
    merge feature/auth
    checkout main
    merge develop tag: "v1.0"
    commit id: "hotfix"

Syntax Guide

Commands: commit, branch, checkout, merge, cherry-pick

Tags: commit tag: "v1.0"

9. Mindmap

Best for: Brainstorming, knowledge organization, hierarchical ideas.

Example: Web Development Stack


  

    
    
    
  

  

    
    
  

  

    
mindmap
  root((Web Dev))
    Frontend
      React
      Vue
      Angular
      Styling
        CSS
        Tailwind
    Backend
      Node.js
      Python
      Go
      APIs
        REST
        GraphQL
    DevOps
      Docker
      CI/CD
      Cloud
        AWS
        GCP

  

  
mindmap
  root((Web Dev))
    Frontend
      React
      Vue
      Angular
      Styling
        CSS
        Tailwind
    Backend
      Node.js
      Python
      Go
      APIs
        REST
        GraphQL
    DevOps
      Docker
      CI/CD
      Cloud
        AWS
        GCP

10. Pie Chart

Best for: Showing percentages, data distribution.

Example: Budget Allocation


  

    
    
    
  

  

    
    
  

  

    
pie showData title Budget Distribution
    "Development" : 40
    "Marketing" : 25
    "Operations" : 20
    "Design" : 15

  

  
pie showData title Budget Distribution
    "Development" : 40
    "Marketing" : 25
    "Operations" : 20
    "Design" : 15

Syntax Guide

pie showData title "Title" - Shows values on chart

11. Timeline

Best for: Chronological events, product roadmaps, history.

Example: Product Roadmap


  

    
    
    
  

  

    
    
  

  

    
timeline
    title Product Roadmap 2024
    section Q1
        January : MVP launch
        February : User feedback
        March : v1.1 release
    section Q2
        April : Mobile app
        May : API v2
        June : Enterprise features
    section Q3
        July : Internationalization
        August : Performance optimization
        September : v2.0 launch

  

  
timeline
    title Product Roadmap 2024
    section Q1
        January : MVP launch
        February : User feedback
        March : v1.1 release
    section Q2
        April : Mobile app
        May : API v2
        June : Enterprise features
    section Q3
        July : Internationalization
        August : Performance optimization
        September : v2.0 launch

12. Kanban Board

Best for: Agile task management, sprint boards.

Example: Sprint Board


  

    
    
    
  

  

    
    
  

  

    
kanban
  Backlog
    [Dark mode]@{ assigned: 'Alice', priority: 'High' }
    [API docs]@{ assigned: 'Bob', priority: 'Medium' }
  In Progress
    [User auth]@{ assigned: 'Carol', priority: 'High' }
    [Dashboard]@{ assigned: 'Dave', priority: 'High' }
  Review
    [Settings page]@{ assigned: 'Eve', priority: 'Medium' }
  Done
    [Landing page]@{ assigned: 'Frank', priority: 'High' }

  

  
kanban
  Backlog
    [Dark mode]@{ assigned: 'Alice', priority: 'High' }
    [API docs]@{ assigned: 'Bob', priority: 'Medium' }
  In Progress
    [User auth]@{ assigned: 'Carol', priority: 'High' }
    [Dashboard]@{ assigned: 'Dave', priority: 'High' }
  Review
    [Settings page]@{ assigned: 'Eve', priority: 'Medium' }
  Done
    [Landing page]@{ assigned: 'Frank', priority: 'High' }

Syntax Guide

Metadata: @{ assigned: 'name', priority: 'High' }

13. Quadrant Chart

Best for: Feature prioritization, strategic analysis, 2x2 matrices.

Example: Feature Priority Matrix


  

    
    
    
  

  

    
    
  

  

    
quadrantChart
    title Feature Priority
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Quick Wins
    quadrant-2 Major Projects
    quadrant-3 Fill Ins
    quadrant-4 Thankless Tasks
    Dark mode: [0.2, 0.8]
    SSO login: [0.7, 0.9]
    CSV export: [0.3, 0.4]
    Animations: [0.8, 0.2]

  

  
quadrantChart
    title Feature Priority
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Quick Wins
    quadrant-2 Major Projects
    quadrant-3 Fill Ins
    quadrant-4 Thankless Tasks
    Dark mode: [0.2, 0.8]
    SSO login: [0.7, 0.9]
    CSV export: [0.3, 0.4]
    Animations: [0.8, 0.2]

Syntax Guide

Coordinates: Range from 0.0 to 1.0 for both x and y

14. Sankey Diagram

Best for: Flow quantities, conversion funnels, budget allocation.

Example: User Conversion Funnel


  

    
    
    
  

  

    
    
  

  

    
sankey-beta

Visitors,Sign up,1000
Visitors,Bounce,2000
Sign up,Trial,600
Sign up,Free,400
Trial,Paid,200
Trial,Churn,400

  

  
sankey-beta

Visitors,Sign up,1000
Visitors,Bounce,2000
Sign up,Trial,600
Sign up,Free,400
Trial,Paid,200
Trial,Churn,400

15. XY Chart

Best for: Bar charts, line charts with numerical data.

Example: Monthly Revenue


  

    
    
    
  

  

    
    
  

  

    
xychart-beta
    title "Monthly Revenue 2024"
    x-axis ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
    y-axis "Revenue ($)" 0 --> 100000
    bar [45000, 52000, 48000, 61000, 55000, 72000]
    line [45000, 52000, 48000, 61000, 55000, 72000]

  

  
xychart-beta
    title "Monthly Revenue 2024"
    x-axis ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
    y-axis "Revenue ($)" 0 --> 100000
    bar [45000, 52000, 48000, 61000, 55000, 72000]
    line [45000, 52000, 48000, 61000, 55000, 72000]

Syntax Guide

Types: bar (bar chart), line (line chart)

16. Block Diagram

Best for: Custom layouts, grid-style arrangements.

Example: System Architecture


  

    
    
    
  

  

    
    
  

  

    
block-beta
    columns 3
    Frontend["Frontend\nReact"]
    space
    Backend["Backend\nNode.js"]
    space:2
    DB[("Database\nPostgreSQL")]

    Frontend --> Backend
    Backend --> DB

  

  
block-beta
    columns 3
    Frontend["Frontend\nReact"]
    space
    Backend["Backend\nNode.js"]
    space:2
    DB[("Database\nPostgreSQL")]

    Frontend --> Backend
    Backend --> DB

Syntax Guide

Layout: columns N defines grid width

Spanning: Block:2 spans 2 columns

17. Architecture Diagram

Best for: Cloud architecture, infrastructure topology.

Example: AWS Infrastructure


  

    
    
    
  

  

    
    
  

  

    
architecture-beta
    group aws(cloud)[AWS Cloud]

    service lb(server)[Load Balancer] in aws
    service api(server)[API Gateway] in aws
    service app(server)[App Server] in aws
    service db(database)[Database] in aws
    service cache(database)[Redis] in aws

    lb:R --> L:api
    api:R --> L:app
    app:B --> T:db
    app:B --> T:cache

  

  
architecture-beta
    group aws(cloud)[AWS Cloud]

    service lb(server)[Load Balancer] in aws
    service api(server)[API Gateway] in aws
    service app(server)[App Server] in aws
    service db(database)[Database] in aws
    service cache(database)[Redis] in aws

    lb:R --> L:api
    api:R --> L:app
    app:B --> T:db
    app:B --> T:cache

Syntax Guide

Icons: server, database, disk, cloud

Directions: L (left), R (right), T (top), B (bottom)

18. Packet Diagram

Best for: Network packet structures, protocol headers.

Example: IPv4 Header


  

    
    
    
  

  

    
    
  

  

    
packet-beta
    0-3: "Version"
    4-7: "IHL"
    8-15: "DSCP/ECN"
    16-31: "Total Length"
    32-47: "Identification"
    48-63: "Flags & Offset"
    64-71: "TTL"
    72-79: "Protocol"
    80-95: "Checksum"
    96-127: "Source IP"
    128-159: "Dest IP"

  

  
packet-beta
    0-3: "Version"
    4-7: "IHL"
    8-15: "DSCP/ECN"
    16-31: "Total Length"
    32-47: "Identification"
    48-63: "Flags & Offset"
    64-71: "TTL"
    72-79: "Protocol"
    80-95: "Checksum"
    96-127: "Source IP"
    128-159: "Dest IP"

Syntax Guide

Format: start-end: "Field name"

19. Requirement Diagram

Best for: Requirements traceability, systems engineering.

Example: System Requirements


  

    
    
    
  

  

    
    
  

  

    
requirementDiagram

requirement uptime_req {
    id: 1
    text: System uptime must be 99.9 percent
    risk: high
    verifymethod: analysis
}

FunctionalRequirement auth_req {
    id: 2
    text: Users must authenticate before accessing data
    risk: high
    verifymethod: test
}

PerformanceRequirement perf_req {
    id: 3
    text: Page load under 200ms
    risk: medium
    verifymethod: test
}

element auth_service {
    type: service
    docref: "auth-spec.pdf"
}

element perf_monitor {
    type: "unit test"
    docref: "LoadTest.cs"
}

auth_service - satisfies -> auth_req
perf_monitor - verifies -> perf_req
auth_req - traces -> uptime_req

  

  
requirementDiagram

requirement uptime_req {
    id: 1
    text: System uptime must be 99.9 percent
    risk: high
    verifymethod: analysis
}

FunctionalRequirement auth_req {
    id: 2
    text: Users must authenticate before accessing data
    risk: high
    verifymethod: test
}

PerformanceRequirement perf_req {
    id: 3
    text: Page load under 200ms
    risk: medium
    verifymethod: test
}

element auth_service {
    type: service
    docref: "auth-spec.pdf"
}

element perf_monitor {
    type: "unit test"
    docref: "LoadTest.cs"
}

auth_service - satisfies -> auth_req
perf_monitor - verifies -> perf_req
auth_req - traces -> uptime_req

Syntax Guide

Types: requirement, FunctionalRequirement, PerformanceRequirement

Risk: low, medium, high

Verify method: test, analysis, inspection, demonstration

Quick Reference: Choosing the Right Diagram

Need Use
Process flow, workflow flowchart
API documentation, message flow sequenceDiagram
Database schema erDiagram
Class structure, OOP classDiagram
State machine, lifecycle stateDiagram-v2
Project timeline gantt
Git branching strategy gitGraph
Cloud infrastructure architecture-beta
Brainstorming, ideas mindmap
Task board, agile kanban
Prioritization matrix quadrantChart
Conversion funnel sankey-beta
Bar/line charts xychart-beta
Percentages pie
Chronological events timeline
User experience journey
Network packets packet-beta
Requirements requirementDiagram
Custom layout block-beta

Tips for Best Results

  1. Use double quotes for labels with spaces: A["Label with spaces"]
  2. Avoid special characters in node IDs: Use underscores instead of hyphens
  3. Always declare direction in flowcharts: flowchart TD or flowchart LR
  4. Keep labels concise: Long labels make diagrams hard to read
  5. Use emoji for visual cues: ✅ Success, ❌ Error, ⚠️ Warning
  6. Test in Mermaid Live Editor: mermaid.live for debugging

Configuration

You can add YAML frontmatter to customize diagram appearance:


  

    
    
    
  

  

    
    
  

  

    
---
config:
  theme: dark
  look: handDrawn
---
flowchart LR
    A --> B

  

  
---
config:
  theme: dark
  look: handDrawn
---
flowchart LR
    A --> B

Themes: default, dark, forest, base, neutral

Looks: default, handDrawn, classic

Built with mdsvr