
Generation of diagrams and flowcharts from text in a similar manner as markdown - nkjoep
https://mermaid-js.github.io/mermaid/
======
abeppu
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.

~~~
kevsim
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](https://kitemaker.co)

~~~
gnabgib
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.

------
dwheeler
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...](https://en.wikipedia.org/wiki/DOT_\(graph_description_language\))
; DOT is widely supported.

There are others too, including:

* Graph Modeling Language: [https://en.wikipedia.org/wiki/Graph_Modelling_Language](https://en.wikipedia.org/wiki/Graph_Modelling_Language) * PGF/TikZ [https://en.wikipedia.org/wiki/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.

------
bdamm
This looks outstanding. I've been hooked on
[https://websequencediagrams.com](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!

------
daltonlp
Direct link to the live editor: [https://github.com/mermaidjs/mermaid-live-
editor](https://github.com/mermaidjs/mermaid-live-editor)

Another diagram-from-text tool:
[https://www.diagram.codes/](https://www.diagram.codes/)

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

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

~~~
prepend
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.

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

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

------
bgorman
Does anyone know how this compares to plantuml?

------
alexott
PlantUML is a good tool for that as well

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

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

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

