 |
In the world of software development and technical documentation, diagrams are a fundamental tool for explaining complex concepts, architectures, process flows, and relationships between components. However, creating and keeping diagrams up to date can quickly become burdensome, especially when using traditional graphic tools.
This is where Mermaid comes in: a text-based description language that allows you to create diagrams in a way that is structured, versionable, and easily maintainable.
What is Mermaid
Mermaid is an open-source library that allows you to generate diagrams and charts from a simple text syntax. Instead of manually drawing shapes and arrows, you describe the diagram through code, which is then automatically rendered.
This “diagram-as-code” approach fits perfectly with modern development and documentation practices.
Comparison with Drag & Drop Tools
Most traditional tools for creating diagrams — such as Microsoft Visio, Lucidchart, or draw.io — are based on a visual approach: you drag elements onto the canvas and connect them.
This model is:
- intuitive
- immediate
- accessible even to non-technical users
With Mermaid, however, the paradigm changes completely: you don't draw, you write.
And this is where an important aspect comes into play:
👉 to use Mermaid effectively, you need to study its syntax.
The Learning Curve: An Initial Investment
Mermaid is not complex, but it's not "zero effort" either. To create well-structured diagrams, you need to:
- understand the different types of diagrams
- learn the keywords (flowchart, sequenceDiagram, classDiagram, etc.)
- understand how to define nodes, relationships, and conditions
- know some syntactic conventions
Those used to drag & drop tools might initially perceive Mermaid as less immediate. There is no graphic canvas to "try and see": there is text to be written correctly.
However, this apparent initial barrier brings an important advantage:
it forces you to formalize your thinking.
Writing a diagram means structuring it logically even before seeing it rendered.
Is there really no drag & drop?
Keep reading to get the full picture of the Mermaid world 😉
Why it's Worth Learning
The initial investment in syntax pays off over time thanks to:
1. Natural Versioning
Being pure text, Mermaid diagrams can be:
- saved in Git repositories
- reviewed via pull requests
- compared with clear and understandable diffs
No more binary files that are impossible to compare.
2. Simplified Maintenance
Updating a diagram means modifying a few lines of text. This reduces the risk of obsolete diagrams and encourages keeping them aligned with the actual code.
3. Structural Consistency
The syntax imposes a certain discipline. This leads to diagrams that are more consistent, less "creative" but more readable and standardized.
4. Integration into Modern Workflows
Mermaid is supported in many Markdown environments and documentation tools, making it perfectly integrable into DevOps flows and documentation pipelines.
A Simple Example
Here is an example of a flowchart written in Mermaid:
flowchart TD
A[User] --> B[Send request]
B --> C{Authenticated?}
C -->|Yes| D[Process the request]
C -->|No| E[Show error]With just a few lines of text, you get a clear, readable, and easily modifiable diagram.
How to Try the Example Right Away
If you want to immediately experiment with the example shown above, you can use mermaid.live, a free online editor that allows you to write Mermaid code and view the generated diagram in real time.
Simply access the site:
https://mermaid.live/
The interface is very simple: on the left side, you can write or paste the diagram code, while the right side shows the automatic rendering. This allows you to make quick changes, better understand the syntax, and get familiar with how Mermaid works without having to install anything.
 |
| mermaid.live |
It's the fastest way to start experimenting and concretely understand the “diagram-as-code” approach.
But there's more... Playground
- change the shapes of elements in the diagram
- change the graphic style of the diagram
- define its orientation
- change the view type - hierarchical vs. adaptive
 |
| Playground editor |
When to Choose Mermaid (and When Not To)
Mermaid is ideal when:
- diagrams are part of technical documentation
- keeping them under version control is important
- the team is used to working with code
- you want to promote consistency and standardization
It might not be the best choice when:
- maximum graphic freedom is needed
- the audience is predominantly non-technical
- the diagram is more oriented toward visual design than logical structure
Does Mermaid Really Not Have Drag & Drop?!
The landscape of tools connected to Mermaid is constantly evolving, and in particular, there is a tool that goes right in the direction of drag & drop: Whiteboard.
Mermaid Whiteboard is a collaborative environment where you can work on diagrams in two modes:
- Text Mode – write the syntax as in normal “diagram-as-code” editors (seen before).
- Visual Drag & Drop Mode – you can move, resize, and connect elements directly with a graphic interface, more similar to a traditional editor.
This duality is designed to adapt to teams with different profiles: those who love control through code and those who prefer working with visual elements.
But what happens to the Mermaid code if you modify the diagram visually?
In Mermaid Whiteboard, when you modify a diagram in visual mode, the tool can regenerate or update the text representation (Mermaid code) to reflect the changes made — this is precisely one of the strong points of the “dual mode” approach offered by Whiteboard, where code and visualization coexist and synchronize.
In other tools or similar plugins, however, the text code remains the primary source of truth: you might see a visual representation, but any advanced modification requires manually updating the Mermaid text or using specific editors that maintain a synchronized state between text and visual — it is not guaranteed in all cases that this happens automatically without confusion.
Conclusion
Mermaid represents a paradigm shift: from “drawn” diagrams to written diagrams.
Yes, it requires learning a syntax.
Yes, it's not as immediate as dragging shapes onto a canvas.
But in exchange, it offers:
- structure
- versionability
- consistency
- integration into modern development flows
- a series of tools (like Whiteboard) to overcome its limitations (like the initial absence of drag & drop)
For technical teams and evolved documentation, it's often an investment that pays off in the medium-to-long term.
But it doesn't end here
- Mermaid GitHub Page where you can find all the info and details → https://github.com/mermaid-js/mermaid?tab=readme-ov-file
- Integrate Mermaid with other platforms (e.g., JIRA) → https://mermaid.js.org/ecosystem/integrations-community.html
Follow me #techelopment
Official site: www.techelopment.it
facebook: Techelopment
instagram: @techelopment
X: techelopment
Bluesky: @techelopment
telegram: @techelopment_channel
whatsapp: Techelopment
youtube: @techelopment
