[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

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

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

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

[redkoala]

Have you thought about updating Mermaid's official docs directly with examples like this?