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.
Want to edit your Mermaid diagram by moving each shape individually, like a typical Gliffy diagram? Just right-click on the diagram and select "Convert to Gliffy."
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.