[sidharthv]

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

[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.

https://github.com/mermaid-js/mermaid/issues/new

[eevilspock]

https://github.com/mermaid-js/mermaid/issues/4136

[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.

[Veuxdo]

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]

Thanks. That is exactly my train of thought on this. Nice to see this positioned also from you.

[sidharthv]

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]

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?