mermaidJStutorial

# Mermaid.js: Create Beautiful Diagrams with Simple Markdown-Like Syntax

Introduction

Mermaid.js is basically a JavaScript tool that lets you create diagrams using text - kinda like how Markdown works for formatting. Instead of dragging boxes around and getting frustrated when they won’t align properly, you just write some simple text, and boom - you get a professional-looking diagram.

What I really love about it is how it bridges the gap between different teams. Developers can use it, but so can project managers and writers. Since everything’s just text, you can keep your diagrams in version control alongside your code. Super handy for tech documentation!

Installation & Setup

Getting Mermaid up and running isn’t complicated at all. There’s a few different ways to do it depending on what you need.

Option 1: CDN Integration (The Easy Way)

Just add this script tag to your HTML file:

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
  mermaid.initialize({ startOnLoad: true });
</script>

Then create your diagram with a div that has the “mermaid” class:

<div class="mermaid">
  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
</div>

Option 2: NPM Installation (For JavaScript Projects)

If your working with Node.js or using bundlers:

npm install mermaid

Then import it and initialize in your JS file:

import mermaid from 'mermaid';
mermaid.initialize({ startOnLoad: true });

Option 3: Mermaid CLI (For Making Static Images)

Need to generate PNG files? Try this:

npm install -g @mermaid-js/mermaid-cli

And then you can use it like:

mmdc -i input.mmd -o output.png

Key Features & Explanation

Mermaid can handle quite a few diagram types - more than I initially expected!

  1. Flowcharts: Perfect for showing processes or workflows
  2. Sequence Diagrams: Great for showing how different parts of a system talk to each other
  3. Gantt Charts: Super useful for project planning and schedules
  4. Class Diagrams: If you’re into object-oriented programming, these are handy
  5. State Diagrams: For showing how states change in a system
  6. Entity Relationship Diagrams: Really useful for database design
  7. Pie Charts: Simple but effective for showing proportions
  8. User Journey Maps: Track how users move through your product or service

You just describe what you want, and Mermaid figures out how to display it. This means you can focus on what’s important - the content - not fiddling with pixels and alignment for hours!

Code Examples

Here are some diagrams that are commonly used:

Flowchart Example

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B

This makes a simple flowchart with decision points. The syntax is pretty intuitive once you get used to it:

Sequence Diagram Example

sequenceDiagram
    participant Browser
    participant Server
    Browser->>Server: GET /api/data
    Server->>Database: SELECT * FROM data
    Database-->>Server: Return results
    Server-->>Browser: Send JSON response

This shows how a browser, server, and database interact:

Gantt Chart Example

gantt
    title Development Roadmap
    dateFormat  YYYY-MM-DD
    section Planning
    Requirements gathering :done, a1, 2023-01-01, 10d
    System design          :active, a2, after a1, 15d
    section Implementation
    Frontend development   :b1, after a2, 20d
    Backend development    :b2, after a2, 25d
    section Testing
    Integration testing    :c1, after b1, 5d

They show:

Class Diagram Example

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

This is really handy for showing:

Result of the Diagrams

Here’s what these diagrams actually look like when rendered:

Flowchart Example

A basic flowchart with decision logic

Sequence Diagram Example

Sequence diagram showing how systems interact - helpful for API docs

Gantt Chart Example

Gantt chart for project planning

Class Diagram Example

Class diagram showing inheritance - great for OOP design discussions

Use Cases

Here are some common use cases for mermaid.js:

Software Development

Project Management

Education & Training

Technical Writing

Conclusion

Mermaid.js has completely changed how I handle diagrams in my technical docs. It solves so many headaches:

  1. Version control actually works now - the diagrams are just text files!
  2. Updating is so much easier - just change the text, there is no need to find the original diagram file
  3. Accessibility is better because there’s a text representation
  4. It fits perfectly with Markdown documentation

If you write technical docs, work in development, or need to plan projects, you should definitely give it a try. The learning curve isn’t steep at all, but what you can do with it is pretty impressive.

Whether you’re mapping out a complex system architecture, planning project timelines, or just trying to explain a process, Mermaid.js lets you create clear diagrams without leaving your text editor.

References & Further Reading