7 ms·
Mermaid Cheat Sheet
- hamandcheese 4y agoLearning 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.
- nick123567 4y agoWhy not learn ppt, keynote or drive slides? More universally applicable and powerful IMO.
- booi 4y agoBecause none of those are as maintainable for engineers as text that can be checked into source control and even in the project itself.
- fzeindl 4y agoThere is https://marp.app/ https://marp.app/ which does Markdown to PPT.
- WirelessGigabit 4y ago- 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
- oaiey 4y agoVery 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, ...
- zelphirkalt 4y agoalso: - 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.
- Scubabear68 4y agoKeynote on Mac fixes many of these complaints, I find it great for diagramming where presentation needs to be very crisp. Agree with others that Mermaid and PlantUML are very useful, but sometimes you need high degrees of visual customization that they don’t give.
- zelphirkalt 4y ago> 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.
- Scubabear68 4y agoI would love it if Mermaid or PlantUML could export to Keynote or similar.
- hamandcheese 4y agoI've made plenty of presentations. It's an extremely cumbersome way to get an idea out, especially in less formal contexts.
- pantulis 4y agoIf 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.
- alexisread 4y agoYou can auto-generate mermaid diagrams from data/class relationships/loosely coupled messages etc. and make them interactive: https://www.npmjs.com/package/vue-mermaid https://www.npmjs.com/package/vue-mermaid Powerpoint doesn't really cover those things.
- asabla 4y agoI feel the same way. 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).
- hamandcheese 4y agoAgreed, 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.
- open592 4y agoI 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.
- agornostal 4y agoIf you want to create sequence diagrams from text that are much more presentable than what you get in Mermaid, check out app.colibridiagrams.net. This app may not have all the diagramming syntax Mermaid or sequencediagram.org has, but should be enough for 99% cases.
- stockhorn 4y agoHow does Mermaid compare to PlantUML? I have only used the latter.
- jensenbox 4y agoI think they have PlantUML in there as well: https://mermaid.js.org/syntax/c4c.html https://mermaid.js.org/syntax/c4c.html
- geoelectric 4y agoSome 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.
- jesperwe 4y agoI 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. [0] https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams https://docs.github.com/en/get-started/writing-on-github/wor...
- wasneverhere 4y agoalso learned today that Mermaid is included in Obsidian - cool stuff!
- chrisweekly 4y agoRelated tangent: Excalidraw is a first-class Obsidian integration; notes in your drawings and/or drawings in your notes, it's very powerful.
- sequence7 4y agoIt's also supported in GitLab [0] Azure DevOps [1] and lots of other places [2] [0] https://docs.gitlab.com/ee/user/markdown.html#mermaid https://docs.gitlab.com/ee/user/markdown.html#mermaid [1] https://learn.microsoft.com/en-us/azure/devops/project/wiki/wiki-markdown-guidance?view=azure-devops#add-mermaid-diagrams-to-a-wiki-page https://learn.microsoft.com/en-us/azure/devops/project/wiki/... [2] https://mermaid.js.org/ecosystem/integrations.html https://mermaid.js.org/ecosystem/integrations.html
- mooreds 4y agoAnd in google docs! https://workspace.google.com/marketplace/app/mermaid/636321283856 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.
- 4y ago
- bigmattystyles 4y agoI’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.
- jensenbox 4y agoWherefore art thou erDiagram? https://mermaid.js.org/syntax/entityRelationshipDiagram.html https://mermaid.js.org/syntax/entityRelationshipDiagram.html
- zelphirkalt 4y agoI 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. [1]: https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_mo... [2]: https://en.wikipedia.org/wiki/File:ERD-artist-performs-song.svg https://en.wikipedia.org/wiki/File:ERD-artist-performs-song....
- natch 4y agoQuestion 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/ 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.
- syncsynchalt 4y agoI 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.
- natch 4y agoWhoosh.
- xavdid 4y agoMermaid'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.
- benatkin 4y agoLike Markdown, Mermaid could use a universal way to add some things to nodes. In sequence diagrams there seems to be no way to add classes to nodes. https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/class https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/c...
- alexisread 4y agoIs this what you're looking for? https://mermaid.js.org/syntax/sequenceDiagram.html https://mermaid.js.org/syntax/sequenceDiagram.html Works fine in VSCode, with the markdown preview mermaid support extension.
- benatkin 4y agoThat'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.
- alexisread 4y agoSorry that should have been https://mermaid.js.org/syntax/sequenceDiagram.html#classes-used https://mermaid.js.org/syntax/sequenceDiagram.html#classes-u... The section where you can add styling by using css classes.
- benatkin 4y agoNo, 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.
- alexisread 4y agoAh I see, I guess you're going to be generating the mermaid diagrams? Depending upon how heavyweight you want to go, something like https://www.npmjs.com/package/vue-mermaid 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.
- bigfudge 4y agoHow does mermaid compare to graphviz? Is it a direct replacement? Is it possible/easy to draw causal diagrams / DAGs with jt?
- alixanderwang 4y agoYou can compare at https://text-to-diagram.com https://text-to-diagram.com (disclaimer: i made it, but it's all open-source, the maintainers of mermaid have contributed to it).
- snooze82 4y agoWorth to mention: you can use ChatGPT to generate mermaid diagrams
- knsv 4y agoCreator 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-about-chatgpt-then-youre-not-being-creative-enough https://www.mermaidchart.com/blog/posts/if-youre-not-excited...
- anyfactor 4y agoThat is cool. TIL. Reading this article now: https://blog.ouseful.info/2022/12/12/generating-diagrams-from-text-generated-by-chatgpt/ https://blog.ouseful.info/2022/12/12/generating-diagrams-fro...
- inferense 4y agothere's also D2 https://d2lang.com/tour/intro/ https://d2lang.com/tour/intro/ which is worth exploring. if anyone wants to try out mermaid in their own .md knowledge base we've built a smooth editor experience in https://acreom.com https://acreom.com (no account required).
- LeBit 4y agoI've been using D2 for a little while now. 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.
- test6554 4y agoI came here expecting a flowchart showing different parts of the body being fish and other parts human and the mythological name for each combination. But I guess I can now make a flowchart showing this. Give a man a fish, etc.
- AceJohnny2 4y agoJust discovering Mermaid. What does it improve over Graphviz's toolset and Dot language? Ref: https://graphviz.org/doc/info/lang.html https://graphviz.org/doc/info/lang.html (tangentially, GraphViz's `gvpr` tool is a woefully underappreciated swiss-army knife for graph processing)
- AceJohnny2 4y agoAt first glance, it appears that Mermaid: 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.
- alexisread 4y agoMermaid, 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: https://www.npmjs.com/package/vue-mermaid https://www.npmjs.com/package/vue-mermaid
- sidharthv 4y agoThis 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) - fully async rendering and parsing - cleaner internals Disclosure: Mermaid maintainer here
- oaiey 4y agoI 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.
- sidharthv 4y agoI feel both have their niche carved out. 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.
- oaiey 4y agoThanks. That is exactly my train of thought on this. Nice to see this positioned also from you.
- 4y ago
- oaiey 4y agoI 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.
- LeBit 4y agoReading the comments, it seems most architects prefer the conventional Visio approach to creating diagrams. 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.
- yesco 4y agoYeah 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.
- markmaglana 4y agoStill waiting for the day someone out there adds some drag-and-drop capability in a Mermaid based UI similar to https://sequencediagram.org/ https://sequencediagram.org/
- robertlagrant 4y agoThat is insanely useful. I am using that in future!
- alixanderwang 4y agoWe offer a drag-and-drop UX, where edits made are written back to the text: https://terrastruct.com https://terrastruct.com (it's not Mermaid, but a similar text-to-diagram language)
- RheingoldRiver 4y agoSaving 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.
- zelphirkalt 4y agoDoes it still count as a cheat sheet, if it is multiple pages long and has "next" buttons in it to navigate to even more pages?
- eevilspock 4y agoThe next button points to the next cheatsheet, not the same cheatsheet. This site is a large collection of cheatsheets.
- jwrallie 4y agoI 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.
- aaaarc 4y agoMermaid 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.
- nutanc 4y agoMermaid+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
- rrgok 4y agoA 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.
- mooreds 4y agoI 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/site/_plugins/jekyll-plantuml-generator.rb https://github.com/FusionAuth/fusionauth-site/blob/master/si... ), but I have recently started using mermaid for a project and like it so far.
- carbolymer 4y agoI'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.
- calimariae 4y agoI use mermaid inside Trilium Notes and absolutely love it!
- pk455 4y agoMermaid 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
- nashashmi 4y agoOT: Anyone know what the status on Mermaid Timeline is? FYI, There is an alternative called Markwhen.
- knsv 4y agoCreator of Mermaid and CTO of Mermaid Chart. We have released Timeline diagrams recently https://mermaid.js.org/syntax/timeline.html https://mermaid.js.org/syntax/timeline.html we also added https://mermaid.js.org/syntax/mindmap.html https://mermaid.js.org/syntax/mindmap.html Both are still experimental, (in beta), but the syntax is set. Personally I really like using Mind maps when taking meeting notes.
- nashashmi 4y agoThank you. I was using the mermaid live editor and did not find it compatible with timeline. Which is why I inquired the status.
- MilStdJunkie 4y agoDon't forget gitgraphs! Super neat. https://mermaid.js.org/syntax/gitgraph.html https://mermaid.js.org/syntax/gitgraph.html
- degosuke 4y agoOnly 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.
- brynjolf 4y agoOne 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 There is an issue on github but no movement.