This is wonderful. I've always felt docs are a weak point of Mermaid as there are many features that are undocumented, and it's a little incoherent overall. Will add a link to this cheat sheet from the official docs.
Also, we just released v10 which
- is 70% smaller (<100 kB gzipped)
- has lazy loaded diagrams (only download diagrams that are used in the site)
I love Mermaid. But my biggest pain point is having to manually wrap text to keep the shapes compact. It's glaringly obvious just looking at this cheatsheet.
Incorporating an algorithm that figures out the optimal auto-wrapping for each shape to make them compact or, alternatively, one that tries to make all the shapes about the same size, should go hand-in-hand with the automatic layout Mermaid already has.
Thank you very much for your work! I learned about mermaid about a year ago, and have used it pretty extensively since, including as a visualization and control interface for a DAG execution framework.
Mermaid’s flow chart layout engine is quite nice, too. I’ve yet to encounter the kind of messes that graphviz comes up with regularly, even with complicated flow charts.
Out of interest, is there an EBNF form for mermaid? I'm asking as I'm looking at notation alternatives for comments in code, for a language I'm designing.
I'd like to be able to write orgdown+mermaid+mathjax equivalent into comments in the language. The language itself needs to be quite formally specified hence the question.
I know markdown isn't actually suitable for this purpose as there are too many edge-case anomalies, I'm hoping mermaid is better specced around the edges.
A single grammar to support all the different use cases would be challenging. But we did have some plans to introduce guidelines to make different diagram syntaxes more consistent.
I've had this need to render just part of a mermaid graph, and I thought of creating a parser to do it. Basically I'd like to render just the part of the graph that flows through a particular node.
Before I go off and write my own parser using this grammar, would it be practical to do this in mermaid's parser already?
I just posted parallel to your post. What is your positioning of mermaid (and friends like plantuml) vs. visually crafted diagrams?
Textual editing, auto-layouting, little work, obviously, but where is the niche compared to visual editors. As an architect, I have challenges using mermaid when communicating to stakeholders.
For developers, text-based editors are an excellent tool to represent not-so-complex logic/procedures where they don't need to spend time worrying about the visual angle. It's easier to integrate into documentation with a ```mermaid, and easy to keep updated.
So there is no context switching involved in opening up a visual editing tool, downloading the image, integrating it to the docs, then having to repeat the whole process again when there are changes.
As an architect, one of your primary responsibilities would be to create high-level diagrams that need to convey a lot more information to the stakeholders, where the weightage of the visual component is high (layout, colors, etc). Which is where Visual editors shine.
The reason is mostly that diagrams from visual editors are basically unmaintainable and therefore are only good for throw-away stuff. Also simple diagrams, especially when you are not entirely sure what you want, are quicker done in a visual editor.
If I need to document a complex system and especially when the documentation has to evolve with the system it is generated diagrams from version controlled text files for me hands down.
I think the sweet spot of text based diagram generators is when the intent is high levels of information delivery at low levels of effort. It is super easy for me to say "a sequence diagram would help convey this concept better" and write up a diagram. Whereas if I had to use a visual tool, it'd be a higher level of effort.
Text based diagrams are also easy to:
* version control
* get feedback on (it's a PR away)
* change
Even though you can style the text based diagrams (see this for plantuml styling: https://plantuml.com/style-evolution ) for a cohesive look and feel, visual based editors are still going to win out. I use them for free form diagrams and also presentations.
For the styling we can't really compete with the visual tools. In Mermaid we have lots of things we can do in that area to make it better though. Both improving the default styling and handling some common use-cases. We could for instance simplify the highlighting of one specific node in a flowchart/class diagram. You can do it right now ofc but you have to make the style/class yourself.
One should be also be aware though that there is a time trap using styling in the visual tools. I spent lots of time making fiddling with styling of boxes in Visio. :)
---
Creator of Mermaid and founder of Mermaid Chart
I had just learned about Mermaid and used it standalone once, when I realized it is also already built into Github Markdown [0], where you can include a diagram by just going ```mermaid <code>```, which is veeery handy. In mermaid.live can also get an SVG URL which works great to paste into many online drawing tools like Miro, Diagrams.net etc.
The interface is a bit clunky (when the diagram text is invalid, you see markup) but it makes it easy to create diagrams that are embeddable in Google docs without reaching for google draw.
I don't know about the others, but Azure DevOps' mermaid support is several releases out of date, or custom-limited to certain features. This means a lot of the examples in the official docs or elsewhere online don't work.
But what is most frustrating is that they don't document what features or version of mermaid they actually support. Microsoft gives a couple examples with links to official Mermaid docs, with a huge vague warning that _some_ things won't work in DevOps.
I think you can embed the mermaid text directly into draw.io/diagrams.net. It becomes a boxed object so a bit painful to edit but make it easy to get a quick diagram up.
Mermaid+chatGPT is a killer combination to create diagrams from plain text.
Describe your diagram in plain text and ask chatGPT to generate Mermaid syntax for said diagram. Then adjust the text generated by chatGPT to get the perfect diagram
Learning a little bit of mermaid is perhaps the highest ROI learning activity I've done in years. Easier, quicker communication about technical ideas - for me it's been a game changer that has made it much easier to get buy in on ideas.
I was painfully reliving my Photoshop days in Miro, trying to create a sequence diagram, when I stumbled upon PlantUML and Mermaid. It was like a breath of fresh air, made things so much easier. Just kicking myself that I didn't know about them earlier.
Mermaid removes most of personal touches and/or design choices. Which makes all diagrams a lot more uniform (which is most of the time a good thing in my book).
Agreed, the desire to make an aesthetically pleasing chart is a huge source of wasted time using WYSIWYG tools. Mermaid is plenty good while unburdening you to simply think about the idea.
- no diffs
- no line attributions
- no easy versioning
- no discussions about whether something should be pushed 10 px to the right
- no reshuffling a whole diagram after you've changed something
- no need to use a shitty office 365 web app (sluggish, slow to load, trusting 10 CDNs)
- ppt is not a graph tool, have fun moving things around after creating a diagram
- no need to rely on proprietary software
- no need to log in anywhere
- no costs
I know there is also the offline old school office suite, but that is more and more deprecated, as MS pushes for everything being a web app.
> Agree with others that Mermaid and PlantUML are very useful, but sometimes you need high degrees of visual customization that they don’t give.
I agree with that and it is the reason I have not yet adopted using Mermaid more.
Would be nice to have Mermaid output some form of standard XML describing the graph and then being able to edit it with a graph editing tool.
I often use yEd for making diagrams, but it is not free/libre software. Still the most capable graph editor I know. It stores graphs as XML "graphml", which is structured data of course. Now if we could have a standard format for graphs and visual attributes of graphs like graphml (maybe even graphml, if it is an open standard?) to export to, when using Mermaid, that would be awesome.
Very good points and clear benefits. My worries are however, the exact layouting demands when you talk to stakeholders. So maybe not a 10px topic but a layering story, LTR-user-to-database thinking, ...
You can auto-generate mermaid diagrams from data/class relationships/loosely coupled messages etc. and make them interactive:
https://www.npmjs.com/package/vue-mermaid
If you try to create a non trivial sequence diagram with a slide deck editor you will become aggravated in a couple of minutes. Now repeat the same thing for a couple scenario diagrams more trying to connect arrows here and there and I guarantee you will throw your computer to a wall.
I actually have much more experience with plantuml (we actually have a plugin which generates diagrams for our jekyll/asciidoc docs site: https://github.com/FusionAuth/fusionauth-site/blob/master/si... ), but I have recently started using mermaid for a project and like it so far.
I'm surprised that mermaid is gaining so much traction in comparison to plantuml which is much more powerful. I guess it's the ease of integration - you don't need to setup java backend just to render diagrams.
I'm still choosing plantuml over mermaid whenever I can. Mermaid has too many quirks and limitations.
I’ve been giving my flow in English to chatgpt and asking it for the mermaid code. It’s really good and even though it’s often not quite right, it’s close enough that I can go in and tweak it to make it correct.
We offer a drag-and-drop UX, where edits made are written back to the text: https://terrastruct.com (it's not Mermaid, but a similar text-to-diagram language)
Question for the author, so, happening on a link to this, are we just supposed to know what Mermaid is? Why not provide a link or a short summary?
Edit: I mean sure, we can google it [https://mermaid.js.org/] but the question stands, because having some small accommodation inline would save the time of many viewers. This seems to be a general problem shared by many resources online, with an easy solution that would eliminate the need to do a search.
I come from the same position of not having heard of mermaid, but this document still worked for me; scrolling 500px I quickly and visually picked up a hint of what "mermaid" must be, and further scrolling let me visually drill down into nuances beyond "just" flowcharting. At that point I stopped skimming and started drilling into details and saw how "markdown-like" the syntax was.
Overall as a sensory and communicative experience the document worked for me and the cognitive bandwidth was high.
I love Markdown. I love textual work. But as an architect, doing diagrams with Mermaid or plantuml is really the wrong thing to do. As an architect you communicate with diagrams. Aesthetics, pixel alignment, colors, custom ordering, ... they all matter when communicating. And these standards, while capable, do not make that easy. So back to visual editors unfortunately.
Formal documentation (like what the systems does etc) ... maybe a different story, because there aesthetics do not matter.
Yeah the best part of the mermaid style approach in my eyes, is how easy it is to update them. Instead of having to open visio, export a svg/png, add the picture to the repo, embed the picture into markdown and then deal with the inevitable text scaling issues; I can just write a few lines of some DSL and instantly see my chart embedded within my markdown preview.
That said, I think it really comes down to if you are creating the chart for a README / code documentation, or if you are creating it for a powerpoint presentation. The latter would obviously miss the mark if done with mermaid, etc since none of the benefits really apply anymore.
Saving this, thank you! I've never had a chance to use Mermaid but I've always wanted to.
A project I wanted to work on a while ago was using Lua to generate Mermaid visualizations of SQL table schema on MediaWiki wikis, based on data from Lua-data-table declarations of the schema, since users don't often have access to the actual MySQL. It's too late for that project, but I still think Mermaid is a very cool tool.
Mermaid's single biggest value prop for me is its ability to connect nodes "well enough" without me needing to fiddle with it. Sometimes I want to ("if I were doing it by hand, I'd put that over there", etc), but I love that it just works. Also that I can encode diagrams in text, so I get all of the tooling that we've developed around text. Feels so obvious in hindsight.
That's just a link to the page about sequence diagrams. I know about sequence diagrams - what I don't know how to do is to add a class to a node on there.
No, that's not what I'm talking about at all. I'm talking about adding a custom css class to a particular node so I can attach behaviors to it with JavaScript.
Mermaid, as you say is ready for the web, so you can add onclick events etc. to say auto-generated diagrams, for interactive charts in a familiar syntax:
Creator of Mermaid here. Great input, quite inspiring! Here are another example of how ChatGPT chart can be integrated with Mermaid and by this having of tediousness with creating diagrams removed:
https://www.mermaidchart.com/blog/posts/if-youre-not-excited...
I wish they would use a more readable notation of labels on those edges in the rendered diagram. Instead of that Crow's Foot notation, just put numbers there (like "1", "n", "m", or if you want to specify even more detail "0..1", "1..1", "1..n", "m..n") and one only needs to remember in which direction to read, not also what some kind of weird notation means. Crow's Foot notation makes the ER diagrams look somewhat unclean.
EDIT: Even the wikipedia[1] example[2] is kind of wrong: A song can be performed by many artists over time.
Mermaid is the fastest tool to write diagrams after pen and paper.
I use it with Markdown Enhanced, it's a powerful tool that quickly ensures your entire team is on the same page and understand the ideas/concepts you're discussing.
Started adding exported images in confluence with the source code attached to the same page, people always get amazed and started adopting it (slowly, I'd say).
The speed is great but not being attached to a heavy tool such as Visio or Gliffy is the game changer.
I was looking into mermaid when I needed to write some Gantz chart, but instead of inserting in a web page, I wanted to insert in a Word document.
I could not figure out a way of resizing it in a way it fits well to the page. The documentation on how to create it was very good, but I couldn't find documentation on how to place it how I wanted, things like configuring its output size.
A little bit of tangential but somehow related to diagramming.
In a flowchart, what is the nicest way to size a diamond dhape which has a long text wrapping across multiple lines? I always find it troublesome and it makes the whole graph not proportional. The diamond shape is one of the least flexible shape. It is so difficult to work with it.
One thing missing from Mermaid is pointing arrows to class members, I use this sometime to create mapping diagram between entities that should be visible in more places than just the implementation code.
With PlantUML you can do this
ClassA::memberB - - |> ClassC::memberD
Only thing that I'd love implemented is the ability to add links on sequence diagrams (probably also on other types, but it's the one I currently try to transition from diagram.io).
What I found very helpful is to add a sequence diagram and add inline links to logs for the given endpoints.
Mermaid looks pretty for most applications and is quite easy to work with, but it starts to feel limited once you start playing with sequence diagrams. Had to bit the bullet and go with PlantUML instead for the time being, but rooting for Mermaid to gain a fuller feature set so I can fully move to it
Some diagrams use the same or very similar syntax, but I think most vary at least a little. PlantUML also supports a number of more esoteric diagrams than Mermaid, though Mermaid supports enough for most people (flow, class, state, sequence, entity, etc).
All said, I saw a recent comparison between the two where they do overlap, and they have very very similar expressive capabilities. One rendered a little better than the other in some diagrams, then vice versa for others.
But I'd say Mermaid being built directly into so many markdown apps now--and not requiring a client/server architecture (or a .jar file)--probably nudges me in its direction.
Also, we just released v10 which
- is 70% smaller (<100 kB gzipped)
- has lazy loaded diagrams (only download diagrams that are used in the site)
- fully async rendering and parsing
- cleaner internals
Disclosure: Mermaid maintainer here