Mermaid Cheat Sheet
jojozhuang.github.io
jojozhuang.github.io
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
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.
Text - Simple, Quick & Dirty diagrams.
Visual - Detailed, well thought out diagrams.
But we cannot easily add layout logic without sacrificing the simplicity of the syntax.
Text - Detailed, well thought out diagrams.
Visual - Simple, Quick & Dirty diagrams.
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.
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'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.
Flowchart: https://github.com/mermaid-js/mermaid/blob/develop/packages/...
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.
Before I go off and write my own parser using this grammar, would it be practical to do this in mermaid's parser already?
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.
All credits for the layout goes to dagre.
We've recently introduced elk and cytoscape as layout engines for some diagrams (flowchart-elk & mindmap).
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.
Any plans?
But the implementation might be a little tricky.
Please raise an issue so we can discuss further, and add it to roadmap if feasible.
[0] https://docs.github.com/en/get-started/writing-on-github/wor...
[0] https://docs.gitlab.com/ee/user/markdown.html#mermaid
[1] https://learn.microsoft.com/en-us/azure/devops/project/wiki/...
https://workspace.google.com/marketplace/app/mermaid/6363212...
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.
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.
https://www.diagrams.net/blog/mermaid-diagrams gives an example.
The svg approach is pretty good too, good idea.
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
- 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
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.
Powerpoint doesn't really cover those things.
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).
This app may not have all the diagramming syntax Mermaid or sequencediagram.org has, but should be enough for 99% cases.
I'm still choosing plantuml over mermaid whenever I can. Mermaid has too many quirks and limitations.
if anyone wants to try out mermaid in their own .md knowledge base we've built a smooth editor experience in https://acreom.com (no account required).
I find it amazing.
I hope C4 diagrams and other types of diagrams will eventually be supported.
But what D2 does, it does it better than the competition.
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.
Overall as a sensory and communicative experience the document worked for me and the cognitive bandwidth was high.
Formal documentation (like what the systems does etc) ... maybe a different story, because there aesthetics do not matter.
Being a solutions architect myself, I am surprised. Maybe because it don't pitch my ideas to non technical people?
I've found PlantUML, Mermaid and now D2, and Python Diagrams to be much better tools to come up with diagrams.
I also love being able to easily refactor the diagrams. Making heavy changes to a Visio/Lucidchart diag is a pain.
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.
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.
Works fine in VSCode, with the markdown preview mermaid support extension.
The section where you can add styling by using css classes.
https://www.npmjs.com/package/vue-mermaid
can work. I've not looked at how it attaches the behavior to the node, there is a way to do it though.
Ref: https://graphviz.org/doc/info/lang.html
(tangentially, GraphViz's `gvpr` tool is a woefully underappreciated swiss-army knife for graph processing)
1. Has a more "true-to-output" declaration format which, like Markdown, aims to be representative of the final result even without processing
2. Is founded in javascript processing, so is ready for the web.
Reading this article now:
https://blog.ouseful.info/2022/12/12/generating-diagrams-fro...
Is it possible/easy to draw causal diagrams / DAGs with jt?
But I guess I can now make a flowchart showing this. Give a man a fish, etc.
https://mermaid.js.org/syntax/entityRelationshipDiagram.html
EDIT: Even the wikipedia[1] example[2] is kind of wrong: A song can be performed by many artists over time.
[1]: https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_mo...
[2]: https://en.wikipedia.org/wiki/File:ERD-artist-performs-song....
But D2 looks very promising. I like the simpler and more intuitive syntax.
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.
With PlantUML you can do this ClassA::memberB - - |> ClassC::memberD
There is an issue on github but no movement.
What I found very helpful is to add a sequence diagram and add inline links to logs for the given endpoints.
FYI, There is an alternative called Markwhen.
Both are still experimental, (in beta), but the syntax is set. Personally I really like using Mind maps when taking meeting notes.
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.