I use this not infrequently when producing documentation. But it's one of those things which is most of the time ok, but when it's not it's very dissatisfying, and I don't have a concise term for the (common) source of that dissatisfaction. When it produces a poor layout, you have to either abandon the tool completely for that use case, or you have to use an entirely different tool set to fix the output (like just editing the SVG).

I think this is a bit challenging, because if you're hand-writing the structure describing the diagram, you likely have some preconception of what it should look like, but the language doesn't give you a real mechanism to express that. And because the diagram is meant to be _looked_ at, the author's preconceptions may actually be quite relevant in how effective the diagram is at communicating content to a later reader. This is in contrast to a compiler, where the author may disagree with the specifics of the output, but so long as it _runs_ to produce correct behavior, the author should not complain too much (i.e. the primary "audience" is the platform which will execute the program).

As an example, only this past weekend, I tried to produce a diagram about an HMM-style graphical model, where nodes occur in sequence in a few parallel families. I had hoped that because of the regular structure of the links, the layout would reflect that regularity. But instead, nodes of each type were sort of all over the place, and the regular structure was actually not immediately visible in the diagram.

> I don't have a concise term for the (common) source of that dissatisfaction

Declarativeness + fragility. That's how I refer to similar experience with PlantUML. Everything is fine, but then if you as much as look at it the wrong way, the diagram gets twisted inside out. It's manageable once you get some experience with it, but I really miss the ability to inject some additional hard constraints into the diagram, like "I don't care what your layout engine thinks, these five nodes are to be in top-left corner and should line up perfectly; arrange everything else around it". I'd happily take 5-10x longer image generation if that's what it takes to have a proper constraint solver involved.

Regardless, it still beats the hell out of arranging diagrams with a mouse. With PlantUML in particular, once you learn how to use the preprocessor to define macros, building larger diagrams becomes super-fast.

I've been considering integrating the ability to embed diagrams written with Mermaid into the issue tracker I'm building [0]. Would you say it's ready/robust enough for that? People typically want to scribble down quick architecture or sequence diagrams (or maybe some class diagrams).

0: https://kitemaker.co

I really like Mermaid, and use it quite a bit (people forget how long they spend dragging boxes, arrows, aligning in Visio/DrawIo), but for some diagram types, you have no control over layout, there isn't even hinting (yet - it continues to improve).

Sequence diagrams are great. I imagine Gantt charts are fine. Flowcharts will sometimes be rendered unintelligibly.. adding/removing a link or new element will completely rearrange the layout. If you have any implied order of your flow (as simple examples on the website imply) this maybe rearranged as your flow gets more complicated. If you want flowcharts over swim lanes (either distinct or implied - think of data-processing ingress on an app), or the start point first and the end point last - this isn't a great tool. There is support for subgraphs, but you have no control over their location either.. so if you want a web-firewall-loadbalancer-app-db type flowchart, it may be rendered in a circle.

100% this. Mermaid is fantastic for the happy path, but as soon as you run into any issues, the lack of flexibility makes it nearly impossible to use (It tames more time to use mermaid than to go back to traditional diagramming tools).

Interesting. Of course, generating diagrams from text isn't new. This especially reminds me of DOT as implemented by Graphviz and others, see: https://en.wikipedia.org/wiki/DOT_(graph_description_languag... ; DOT is widely supported.

There are others too, including:

* Graph Modeling Language: https://en.wikipedia.org/wiki/Graph_Modelling_Language * PGF/TikZ https://en.wikipedia.org/wiki/PGF/TikZ * pic (for troff)

If someone has used both Mermaid & an alternative I'd be curious to hear a detailed compare & contrast.

This looks outstanding. I've been hooked on https://websequencediagrams.com and it has transformed my creation of sequence diagrams from dreaded chores to joyful learning-by-doing experience. This project looks to replicate some of the success of that site, uses very similar syntax for sequence diagrams, and can do much more. I'm psyched!

Direct link to the live editor: https://github.com/mermaidjs/mermaid-live-editor

Another diagram-from-text tool: https://www.diagram.codes/

I find that the gantt chart and sequence diagram are really useful for documentation, but the class diagrams and flowcharts aren’t useful for anything but really simple flows. Basically the diagrams are just too cluttered to read, not sure exactly why, but I think its the spacing due to graph issues.

Search for "site:mermaid-js.github.io graphviz" returned nothing. Odd. So how does it compare?

I tried both and the javascript support for mermaid is better and has run without problem. I first found it looking for a markdown plug-in for diagrams and mermaid has been great for that.

I like mermaid but actually prefer PlantUML - I think PlantUML has a slightly simpler declarative syntax that fits better with the spirit of Markdown, and with the macros and layout hinting you can usually tame complex diagrams whereas I find with Mermaid it ends up being more incomprehensible.

Some bikeshedding:

What about "Top-Down Graph" or "Graph Top-Down" rather than "graph TD"?

Or "Entity Relationship Diagram" instead of "erDiagram"?

Just to make it even more easy to read. The others could remain as shorthands.

Does anyone know how this compares to plantuml?

PlantUML is a good tool for that as well

The principle sounds like LaTeX and its various packages for creating diagrams.

markdeep which includes plantuml and various other tools. Note too that plantUML has evolved into a more general diagramming tool with standard library icons

Obligatory Emacs plug for ob-mermaid, wsd-mode and plantuml-mode