Get the top HN stories in your inbox every day.
sidharthv
eevilspock
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
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.
iroddis
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
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).
alexisread
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
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.
jclermont
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?
oaiey
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
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
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.
oaiey
Thanks. That is exactly my train of thought on this. Nice to see this positioned also from you.
mooreds
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.
knsv
Good summary @moonreds, I fully agree.
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
redkoala
Have you thought about updating Mermaid's official docs directly with examples like this?
jesperwe
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...
sequence7
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/...
mooreds
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.
addled
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.
wasneverhere
also learned today that Mermaid is included in Obsidian - cool stuff!
chrisweekly
Related tangent: Excalidraw is a first-class Obsidian integration; notes in your drawings and/or drawings in your notes, it's very powerful.
mwexler
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.
mLuby
Notion has a nice split-screen preview + code approach.
nutanc
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
hamandcheese
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
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.
agornostal
If 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.
asabla
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
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.
nick123567
Why not learn ppt, keynote or drive slides? More universally applicable and powerful IMO.
WirelessGigabit
- 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 somethingzelphirkalt
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
oaiey
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, ...
booi
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
There is https://marp.app/ which does Markdown to PPT.
alexisread
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.
pantulis
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.
hamandcheese
I've made plenty of presentations. It's an extremely cumbersome way to get an idea out, especially in less formal contexts.
mooreds
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.
carbolymer
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.
bigmattystyles
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.
inferense
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
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.
markmaglana
Still waiting for the day someone out there adds some drag-and-drop capability in a Mermaid based UI similar to https://sequencediagram.org/
alixanderwang
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)
robertlagrant
That is insanely useful. I am using that in future!
natch
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
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
Whoosh.
oaiey
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
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
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.
RheingoldRiver
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.
xavdid
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.
Get the top HN stories in your inbox every day.
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