A Comprehensive Guide to Mermaid Diagrams

Documenting your work takes time you don’t always have, but a lack of documentation is harmful to productivity and collaboration.

Mermaid diagrams provide a quicker way to document systems and code without having to drag, drop, or connect a single shape manually — making it faster to create the documentation that connects your team and supports your future development efforts. 

What Are Mermaid Diagrams?

Mermaid diagrams are code-based diagrams that represent structures and processes, generated using Markdown-inspired text definitions that are easy to write and modify. 

Many diagram types important to software documentation can be generated with Mermaid, including UML diagrams and entity-relationship diagrams.

Why Do Developers Use Mermaid?

Often, developers don’t want to spend time dragging and dropping shapes to create a diagram illustrating their work when it’s faster for them to express their ideas in writing. Mermaid provides a way to write code that represents a system or process and then automatically generate a diagram visualizing that code. This is part of a larger movement known as "diagrams as code."

Mermaid and other diagrams as code frameworks allow teams to develop visual documentation quickly and efficiently, creating a valuable resource for stakeholder communication and a reference for future work. 

Mermaid Diagram Tutorial Video

Watch this quick tutorial to learn how to generate Mermaid diagrams in Gliffy! Make sure you’ve started your free trial in Confluence Cloud or Data Center so you can follow along.

Prefer written instructions? Keep reading to check out our how-to guide, with screenshots included!

How to Generate Mermaid Diagrams in Gliffy

Mermaid diagrams work a little differently than any other way to diagram in Gliffy. To learn how to use Gliffy’s Mermaid diagramming functionality, follow along with these step-by-step instructions.

1. Select the Lightbulb Icon

When you open a new Gliffy diagram, you’ll notice a lightbulb icon on the far left side of your screen. Click on this icon to see more ways to generate diagrams. 

2. Enter the Editing Modal

Selecting “Mermaid” will bring you into the diagram editing modal. This is where you’ll create and modify your diagram. 

3. Select And Modify Your Diagram

Once you’re in the editing modal, choose the diagram type you want and modify the code as desired. The sample diagrams you’ll find in the editing modal are short and simple, but if you’re looking for more detailed examples to start from, keep reading — we'll share a few samples later in this tutorial.

💡 Diagramming Tip: AI can help you generate diagrams! For example, you can ask ChatGPT to give you Mermaid text for an entity-relationship diagram with certain parameters, then copy and paste the result it provides into Gliffy's Mermaid editor.

AI isn’t always accurate, so you may have to make some changes after pasting the generated text, but this will give you a quick and easy starting point for your Mermaid diagram. 

4. Add the Diagram to Your Canvas

Once the diagram contents have been modified to your liking, click “Build Diagram” in the lower left-hand corner of the editing modal to add the diagram to your Gliffy canvas. If you need to make further edits to the diagram, you can double-click on it to re-enter the editing modal. 

If you’ve used Gliffy before, you’re probably familiar with its drag-and-drop interface, but Mermaid diagrams work a little differently. You can’t edit a Mermaid diagram directly from the canvas like you would any other shape — you’ll have to re-enter the editing modal in order to change the diagram. 

5. Add the Finishing Touches

Want to add extra shapes to your diagram? Navigate back to the shape library by clicking the square icon above the lightbulb icon on the left panel of your screen.

You can also add sticky notes explaining parts of your diagram or annotate your diagram using the freehand drawing tool. 

Once your diagram is complete, simply save and return to Confluence!

Mermaid Diagram Examples

Looking for a template to build your Mermaid diagram from? Here are a few examples of technical diagram types and the code used to generate them. 

Sequence Diagram 

sequenceDiagram
    participant Customer
    participant Chatbot
    participant Airline

    Customer->>Chatbot: Request Flight Rebooking
    Chatbot-->>Customer: Greet and Gather Information
    Customer->>Chatbot: Provide Booking Reference
    Chatbot-->>Airline: Request Booking Information
    Airline-->>Chatbot: Provide Booking Details
    Chatbot-->>Customer: Display Booking Details
    Customer->>Chatbot: Request Rebooking Options
    Chatbot-->>Airline: Request Available Flights
    Airline-->>Chatbot: Provide Rebooking Options
    Chatbot-->>Customer: Display Rebooking Options
    Customer->>Chatbot: Select Preferred Option
    Chatbot-->>Airline: Initiate Rebooking Process
    Airline-->>Chatbot: Confirm Rebooking
    Chatbot-->>Customer: Rebooking Successful

State Diagram

stateDiagram
    [*] --> InInventory: In Inventory
    InInventory --> InUse: Issued to User
    InInventory --> InMaintenance: Maintenance Required
    InMaintenance --> InInventory: Maintenance Completed
    InInventory --> Retired: End of Life
    InUse --> InMaintenance: Malfunction
    InUse --> InInventory: Returned

    state InInventory {
        [*] --> Available: Available
        Available --> Issued: Issued
        Issued --> Available: Returned
    }

    state InUse {
        [*] --> Operational: Operational
        Operational --> Malfunction: Malfunction
    }

Entity-Relationship Diagram

erDiagram
    Passenger ||--o{ Booking : "Makes"
    Booking }|..|{ Flight : "Books"
    Airport }|..|{ Flight : "Originates from"
    Airport }|..|{ Flight : "Arrives at"
    Flight }|..|{ Aircraft : "Operated by"
    Aircraft }|..|{ Flight : "Assigned to"

    Passenger {
        int PassengerID
        string FirstName
        string LastName
        string Email
        string PhoneNumber
    }
    Booking {
        int BookingID
        datetime BookingDate
        string SeatNumber
    }
    Airport {
        int AirportCode
        string Name
        string Location
    }
    Flight {
        int FlightNumber
        datetime DepartureTime
        datetime ArrivalTime
    }
    Aircraft {
        int AircraftID
        string Model
        int Capacity
    }

    Passenger }|..|{ Booking : "Books"
    Booking }|..|{ Flight : "Assigned to"
    Airport }|..|{ Flight : "Departure Airport"
    Airport }|..|{ Flight : "Arrival Airport"
    Flight }|..|{ Aircraft : "Assigned to"

Generate a Code-Based Mermaid Diagram Today

Whether you’re starting from scratch or using one of our samples, following the steps outlined here will set you up for success as you create your next Mermaid diagram! Don’t forget to start your free trial of Gliffy so you can generate Mermaid diagrams directly in Confluence.

TRY GLIFFY