[HN Gopher] Mermaid Cheat Sheet
___________________________________________________________________
Mermaid Cheat Sheet
Author : mooreds
Score : 319 points
Date : 2023-02-23 03:29 UTC (19 hours ago)
(HTM) web link (jojozhuang.github.io)
(TXT) w3m dump (jojozhuang.github.io)
| jesperwe wrote:
| 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.
|
| [0] https://docs.github.com/en/get-started/writing-on-
| github/wor...
| mLuby wrote:
| Notion has a nice split-screen preview + code approach.
| sequence7 wrote:
| It'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
|
| [1] https://learn.microsoft.com/en-
| us/azure/devops/project/wiki/...
|
| [2] https://mermaid.js.org/ecosystem/integrations.html
| addled wrote:
| 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.
| mooreds wrote:
| And in google docs!
|
| 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.
| wasneverhere wrote:
| also learned today that Mermaid is included in Obsidian - cool
| stuff!
| chrisweekly wrote:
| Related tangent: Excalidraw is a first-class Obsidian
| integration; notes in your drawings and/or drawings in your
| notes, it's very powerful.
| mwexler wrote:
| 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.
|
| https://www.diagrams.net/blog/mermaid-diagrams gives an
| example.
|
| The svg approach is pretty good too, good idea.
| nutanc wrote:
| 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
| rrgok wrote:
| 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.
| xavdid wrote:
| 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.
| inferense wrote:
| there's also D2 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
| (no account required).
| LeBit wrote:
| I'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.
| oaiey wrote:
| 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.
| LeBit wrote:
| Reading 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 wrote:
| 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.
| benatkin wrote:
| Like 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/c...
| alexisread wrote:
| Is this what you're looking for?
| https://mermaid.js.org/syntax/sequenceDiagram.html
|
| Works fine in VSCode, with the markdown preview mermaid support
| extension.
| benatkin wrote:
| 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.
| alexisread wrote:
| Sorry that should have been https://mermaid.js.org/syntax/s
| equenceDiagram.html#classes-u...
|
| The section where you can add styling by using css classes.
| benatkin wrote:
| 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.
| alexisread wrote:
| Ah 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
|
| can work. I've not looked at how it attaches the behavior
| to the node, there is a way to do it though.
| mooreds wrote:
| 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.
| bigmattystyles wrote:
| 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.
| bigfudge wrote:
| How does mermaid compare to graphviz? Is it a direct replacement?
|
| Is it possible/easy to draw causal diagrams / DAGs with jt?
| alixanderwang wrote:
| You can compare at https://text-to-diagram.com (disclaimer: i
| made it, but it's all open-source, the maintainers of mermaid
| have contributed to it).
| aaaarc wrote:
| 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.
| LeBit wrote:
| I think Mermaid is better than PlantUML to write something
| quickly.
|
| But D2 looks very promising. I like the simpler and more
| intuitive syntax.
|
| https://text-to-diagram.com/
| tonerow wrote:
| For simpler, more intuitive syntax give flowchart.fun a try
| markmaglana wrote:
| Still waiting for the day someone out there adds some drag-and-
| drop capability in a Mermaid based UI similar to
| https://sequencediagram.org/
| robertlagrant wrote:
| That is insanely useful. I am using that in future!
| alixanderwang wrote:
| 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)
| hamandcheese wrote:
| 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.
| open592 wrote:
| 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.
| nick123567 wrote:
| Why not learn ppt, keynote or drive slides? More universally
| applicable and powerful IMO.
| booi wrote:
| Because none of those are as maintainable for engineers as
| text that can be checked into source control and even in the
| project itself.
| fzeindl wrote:
| There is https://marp.app/ which does Markdown to PPT.
| alexisread wrote:
| 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
|
| Powerpoint doesn't really cover those things.
| WirelessGigabit wrote:
| - 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 wrote:
| 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, ...
| zelphirkalt wrote:
| also: - 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 wrote:
| Keynote 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 wrote:
| > 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 wrote:
| I would love it if Mermaid or PlantUML could export to
| Keynote or similar.
| hamandcheese wrote:
| I've made plenty of presentations. It's an extremely
| cumbersome way to get an idea out, especially in less formal
| contexts.
| pantulis wrote:
| 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.
| asabla wrote:
| I 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 wrote:
| 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.
| nashashmi wrote:
| OT: Anyone know what the status on Mermaid Timeline is?
|
| FYI, There is an alternative called Markwhen.
| test6554 wrote:
| I 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.
| zelphirkalt wrote:
| Does 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 wrote:
| The next button points to the next cheatsheet, not the same
| cheatsheet. This site is a large collection of cheatsheets.
| AceJohnny2 wrote:
| Just discovering Mermaid. What does it improve over Graphviz's
| toolset and Dot language?
|
| Ref: https://graphviz.org/doc/info/lang.html
|
| (tangentially, GraphViz's `gvpr` tool is a woefully
| underappreciated swiss-army knife for graph processing)
| AceJohnny2 wrote:
| At 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 wrote:
| 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:
|
| https://www.npmjs.com/package/vue-mermaid
| calimariae wrote:
| I use mermaid inside Trilium Notes and absolutely love it!
| RheingoldRiver wrote:
| 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.
| snooze82 wrote:
| Worth to mention: you can use ChatGPT to generate mermaid
| diagrams
| anyfactor wrote:
| That is cool. TIL.
|
| Reading this article now:
|
| https://blog.ouseful.info/2022/12/12/generating-diagrams-fro...
| jwrallie wrote:
| 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.
| sidharthv wrote:
| 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)
|
| - fully async rendering and parsing
|
| - cleaner internals
|
| Disclosure: Mermaid maintainer here
| oaiey wrote:
| 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.
| sidharthv wrote:
| I 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.
| weinzierl wrote:
| For me it's the exact opposite:
|
| 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.
| Veuxdo wrote:
| Very much agree with this. In fact wrote something on
| this last year almost to the day:
| https://www.ilograph.com/blog/posts/its-time-to-drop-
| drag-an...
| oaiey wrote:
| Thanks. That is exactly my train of thought on this. Nice
| to see this positioned also from you.
| sidharthv wrote:
| Themes and colors, we can do. I've seen people drawing
| some spectacular diagrams with Mermaid.
|
| But we cannot easily add layout logic without sacrificing
| the simplicity of the syntax.
| mooreds wrote:
| 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.
| iroddis wrote:
| 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.
| sidharthv wrote:
| Thank you!
|
| All credits for the layout goes to dagre.
|
| We've recently introduced elk and cytoscape as layout engines
| for some diagrams (flowchart-elk & mindmap).
| redkoala wrote:
| Have you thought about updating Mermaid's official docs
| directly with examples like this?
| eevilspock wrote:
| 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.
|
| Any plans?
| sidharthv wrote:
| This would really be a good UX improvement.
|
| But the implementation might be a little tricky.
|
| Please raise an issue so we can discuss further, and add it
| to roadmap if feasible.
|
| https://github.com/mermaid-js/mermaid/issues/new
| eevilspock wrote:
| https://github.com/mermaid-js/mermaid/issues/4136
| alexisread wrote:
| 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.
| sidharthv wrote:
| Mermaid as a whole doesn't have a formally specified grammar.
| Individual diagrams have their grammar in a .jison file.
|
| 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.
| jensenbox wrote:
| Wherefore art thou erDiagram?
|
| https://mermaid.js.org/syntax/entityRelationshipDiagram.html
| zelphirkalt wrote:
| 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.
|
| [1]:
| https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_mo...
|
| [2]: https://en.wikipedia.org/wiki/File:ERD-artist-performs-
| song....
| pk455 wrote:
| 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
| natch wrote:
| 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.
| syncsynchalt wrote:
| 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.
| natch wrote:
| Whoosh.
| stockhorn wrote:
| How does Mermaid compare to PlantUML? I have only used the
| latter.
| jensenbox wrote:
| I think they have PlantUML in there as well:
| https://mermaid.js.org/syntax/c4c.html
| geoelectric wrote:
| 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.
___________________________________________________________________
(page generated 2023-02-23 23:02 UTC)