Skip to main content

Mermaid: Diagramming and Charting with Markdown

Mermaid is a powerful JavaScript-based diagramming and charting tool that uses a Markdown-inspired text definition language. This allows you to create diagrams and visualizations dynamically from text descriptions, making it ideal for documenting system architectures, designing workflows, and visualizing data.

What is Mermaid?​

Mermaid lets you create various diagrams using a simple, human-readable syntax. It's especially useful for developers, technical writers, and anyone who needs to create diagrams quickly and efficiently. The diagrams are rendered in the browser, and can be easily embedded in websites, documentation, and presentations.

Key Features:

  • Markdown-Inspired Syntax: Easy-to-learn and use syntax based on Markdown.
  • Various Diagram Types: Supports flowcharts, sequence diagrams, class diagrams, state diagrams, entity relationship diagrams (ERDs), Gantt charts, pie charts, and more.
  • Live Editor: Provides a live editor for creating and previewing diagrams.
  • Integration: Integrates with many platforms, including GitHub, GitLab, and various documentation generators.
  • Customizable: Offers customization options for styling and appearance.
  • Client-Side Rendering: Diagrams are rendered on the client-side, making it lightweight and fast.

Why Use Mermaid?​

  • Ease of Use: The simple syntax makes it easy to create complex diagrams without requiring specialized tools or skills.
  • Version Control: Diagrams are stored as text, making them easy to track with version control systems like Git.
  • Collaboration: Enables collaboration by allowing multiple people to contribute to and review diagrams.
  • Documentation: Integrates seamlessly with documentation generators like Docusaurus, allowing diagrams to be included directly in documentation.
  • Automation: Diagrams can be generated programmatically from data sources or code.

Diagram Types​

Mermaid supports a wide range of diagram types:

  • Flowcharts: Visualize processes and workflows.
  • Sequence Diagrams: Illustrate interactions between objects or systems over time.
  • Class Diagrams: Model the structure of classes and their relationships.
  • State Diagrams: Represent the states of an object or system and the transitions between them.
  • Entity Relationship Diagrams (ERDs): Model the relationships between entities in a database.
  • Gantt Charts: Visualize project schedules and timelines.
  • Pie Charts: Display data as proportions of a whole.
  • Git Graphs: Visualize the structure of Git repositories.
  • User Journey: Visualize the steps a user takes to accomplish a goal.

Getting Started​

The easiest way to get started with Mermaid is to use the online live editor:

This editor allows you to create and preview diagrams in real-time. You simply enter the Mermaid code in the editor, and the diagram is rendered automatically.

Example Diagrams and Syntax​

Here are some examples of Mermaid syntax and the resulting diagrams:

1. Flowchart

graph TD
    A[Start] --> B{Is it?};
    B -- Yes --> C[OK];
    B -- No --> D[Crash!];
    C --> E[End];
    D --> E;

Result: (This would render a simple flowchart with a start, decision, and end.)

2. Sequence Diagram

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I am good thanks!

Result: (This would render a sequence diagram showing a simple message exchange between Alice and Bob.)

3. Class Diagram

classDiagram
    Class01 <|-- Class02
    Class03 *-- Class04
    Class05 o-- Class06
    Class07 .. Class08
    Class09 --> Class10
    Class11 -- Class12
    Class13 ..> Class14
    Class15 --o Class16
    Class17 --> Class18 : Label

Result: (This would render a class diagram showing various relationships between classes.)

4. ER Diagram

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER {
        string custId PK
        string name
        string address
    }
    ORDER {
        int orderId PK
        int custId FK
        string orderDate
    }
    LINE-ITEM {
        int orderId FK
        int productId FK
        int quantity
    }

Result: (This would render a simple ER diagram showing the relationships between customers, orders, and line items.)

Integration Options​

Mermaid can be integrated into various platforms and tools:

  • Docusaurus: Use the Docusaurus plugin to embed Mermaid diagrams directly in your documentation. npm install @docusaurus/remark-plugin-mermaid
  • Markdown Editors: Many Markdown editors support Mermaid syntax highlighting and previewing.
  • Websites and Applications: Include the Mermaid library in your HTML to render diagrams on the client-side. See the docs on mermaidjs.github.io for the latest CDN and install instructions.

Customization​

Mermaid diagrams can be customized using CSS styling and configuration options. You can customize the appearance of diagrams to match your website or application's branding. The official documentation provides a comprehensive guide to customization options.

Resources​

Conclusion​

Mermaid is a versatile and easy-to-use diagramming tool that can significantly improve your documentation, design workflows, and data visualization. Its Markdown-inspired syntax, wide range of diagram types, and integration options make it a valuable asset for developers, technical writers, and anyone who needs to create diagrams quickly and efficiently. Start using Mermaid today to enhance your projects and streamline your communication.