If you’ve ever wanted to add diagrams to your technical posts without firing up a separate design tool, Mermaid.js is exactly what you need. It lets you define flowcharts, sequence diagrams, class diagrams, and more using simple text syntax right inside your Markdown.

What is Mermaid.js?

Mermaid.js is a JavaScript tool that renders text-defined diagrams using Markdown-inspired syntax. It allows you to create flowcharts, sequence diagrams, class diagrams, ER diagrams, state diagrams, and more - all from plain text in your markdown files.

Flowchart

Flowcharts work best when you need to show how something flows — a decision tree, a user journey, or just a process with a few branches.

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> E[Check logs]
    E --> F[Fix issue]
    F --> B
    C --> G[Deploy to production]
    G --> H[Monitor]
    H -->|Issues| D
    H -->|Stable| I[Done]

Sequence Diagram

Sequence diagrams are handy when you want to show how several actors interact over time — who calls whom, who responds, and in what order.

sequenceDiagram
    participant User
    participant Browser
    participant Server
    participant Database

    User->>Browser: Submit form
    Browser->>Server: POST /api/submit
    Server->>Database: Save data
    Database-->>Server: Confirmation
    Server-->>Browser: 200 OK
    Browser-->>User: Success message

Class Diagram

Class diagrams come in useful when you want to sketch out the structure of an object-oriented system — showing what classes exist, what fields they have, and how they relate to each other.

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
        +move()
    }
    class Dog {
        +String breed
        +bark()
        +fetch()
    }
    class Cat {
        +String color
        +meow()
        +purr()
    }
    Animal <|-- Dog
    Animal <|-- Cat

Entity Relationship Diagram

ER diagrams are the go-to when you’re designing a database and want to see how your entities relate — users, orders, products, the connections between them.

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--o{ PRODUCT : contains
    USER ||--o{ REVIEW : writes
    PRODUCT ||--o{ REVIEW : has

    USER {
        string id
        string email
        string name
        date created_at
    }
    ORDER {
        int id
        date order_date
        string status
    }
    PRODUCT {
        int id
        string name
        decimal price
    }
    REVIEW {
        int id
        int rating
        string comment
    }

State Diagram

State diagrams help you track all the possible states something can be in, and what transitions exist between those states.

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: Submit
    Review --> Approved: Reviewer OK
    Review --> Draft: Needs changes
    Approved --> Published: Publish
    Published --> [*]
    Published --> Draft: Unpublish

How to Use

Using a diagram in your posts is straightforward: wrap your Mermaid code in a fenced block with the language set to mermaid.

```mermaid
graph TD
    A[Start] --> B[End]
```

The diagram will automatically be rendered when the page loads. All diagrams in this theme use a dark theme that matches the cyberpunk aesthetic.

Conclusion

Whether you’re documenting system architecture, walking through a process, or mapping out a database schema, diagrams make your content easier to follow. Mermaid lets you add them without leaving your markdown editor.