
Mermaid: Markdown-like generation of diagrams and flowcharts from text - tomcam
https://github.com/knsv/mermaid
======
lobster_johnson
Mermaid is great, and I've used it for architectural diagrams of how tech
stacks are put together, or data flows between apps. But it only produces
marginally nicer-looking diagrams than Graphviz, and it optimizes badly
against unnecessary line intersections (e.g. it's far too easy to end up with
this, even in trivial diagrams:
[https://imgur.com/Tkpa9fD](https://imgur.com/Tkpa9fD)).

My wish is for a diagram renderer with a smarter layout algorithm that heavily
optimizes for direction and cleanness, understands grouping really well, and
comes with easy ways to apply SVG styles. I like Google's diagrams in this
regard:

[http://donatz.info/wp-content/uploads/2017/10/google-
cloud-a...](http://donatz.info/wp-content/uploads/2017/10/google-cloud-
architecture-beautiful-on-with-regard-to-real-time-bidding-
architectures-1.png)

[http://donatz.info/wp-content/uploads/2017/10/google-
cloud-a...](http://donatz.info/wp-content/uploads/2017/10/google-cloud-
architecture-lovely-on-intended-designing-etl-for-a-native-data-
warehouse-5.png)

[http://donatz.info/wp-content/uploads/2017/10/google-
cloud-a...](http://donatz.info/wp-content/uploads/2017/10/google-cloud-
architecture-fine-on-intended-for-platform-blog-understanding-pricing-6.png)

~~~
qznc
I would love a GraphViz like tool which produces more beautiful graphs.
Example:

[https://www.flickr.com/photos/gigile/3505955900](https://www.flickr.com/photos/gigile/3505955900)

Note how well the overall graph fits into the rectangular format. GraphViz
sucks at this. This image is not perfect though. There are a few unnecessary
crossovers.

Another thing I miss in GraphViz are line jumps:

[https://support.office.com/en-us/article/add-or-remove-
conne...](https://support.office.com/en-us/article/add-or-remove-connector-
line-jumps-1a5516db-0212-4352-90dd-fc9cfd4018ed)

~~~
Heisgone01
The following code is pretty easy to hack:

[https://archive.codeplex.com/?p=graphviz4net](https://archive.codeplex.com/?p=graphviz4net)

I started to customize it but lacked times. The biggest challenge was to be
able to convert the WPF rendering into something else, which I couldn’t figure
out. I changed the canvas for another one with a better zoom function but
couldn’t export or print the canvas.

------
gegtik
You should also check out [http://plantuml.com/](http://plantuml.com/) An
online editor/renderer is available at
[http://planttext.com/](http://planttext.com/)

~~~
CMCDragonkai
Main issue is being able to render in-browser. Which mermaid can. Wish
plantuml can be ported to js.

~~~
BLanen
Wouldn't it?

Graphviz can be ported to JS, I found an example although I didn't try it.

~~~
erichdongubler
GraphViz in the browser was made possible by `emscripten`, which is
essentially a JavaScript compiler target. In that sense, there's not a
implementation in a language besides C++ that's gotten much traction.

------
michaelbuckbee
I really like this, it's a bit buried in their "sibling projects" but there is
a live rendering version as well:

[https://mermaidjs.github.io/mermaid-live-
editor/](https://mermaidjs.github.io/mermaid-live-editor/)

Very cool project.

~~~
stevemk14ebr
Good find. This should be linked in the readme

------
IIAOPSW
graphviz
[http://www.graphviz.org/download/](http://www.graphviz.org/download/)

also the DOT language has been around for ages.

~~~
krapht
Yeah, I'd like a comparison to graphviz/plantuml, not sure how this is
different.

~~~
nerdponx
It's almost identical, and it's a shame they didn't just make a Graphviz
compiler for te browser.

~~~
bitexploder
There is an emscripten compiled graphviz already. Works fine.

~~~
Groxx
Yea, I've used [http://www.webgraphviz.com/](http://www.webgraphviz.com/) for
quite a while. Toss in a tiny script to click the button after every keypress,
and voila: live-editing graphviz stuff. It's magical.

------
mark_l_watson
I understand that Mermaid is designed to generate diagrams into HTML DOMs, not
my use case. I have experimented over the years with text based diagram tools
to replace OmniGraffle for figures in the books I write.

My writing process is fairly streamlined and efficient, except for generating
OmniGraffle figures which takes some time.

My day job is in machine learning (30+ years) and I have considered creating a
model to map my hand drawn figures to something nicer - not too difficult,
except for a lack of training data.

~~~
teleclimber
Have a look at drawexpress which turns hand gestures into shapes. It's
excellent, one of my favorite apps.

[http://www.drawexpress.com](http://www.drawexpress.com)

------
os72
Typora ([https://typora.io/](https://typora.io/)) can render mermaid and is
useful for local markdown editing in general. It's quite cool.

~~~
GordonS
Any idea if it supports Asciidoc? It wasn't obvious to me where to find info
on the supported markdown languages on their website.

~~~
mpcjanssen
It is supported by asciidoctor-diagram.

------
retzkek
The Diagram panel plugin for Grafana uses this, you can attach metrics to
nodes in the diagram and color them according to a gradient. I like using it
instead of single stat panels for giving a quick overview of the state of the
system, then including detailed graphs underneath.
[https://grafana.com/plugins/jdbranham-diagram-
panel](https://grafana.com/plugins/jdbranham-diagram-panel)

------
binarycrusader
See also markdeep:

[https://casual-effects.com/markdeep](https://casual-effects.com/markdeep)

~~~
HIPisTheAnswer
> Markdeep is a technology for writing plain text documents that will look
> good in any web browser

I couldn't read their website on my mobile...

~~~
stareatgoats
Me neither, on desktop: ERR_BAD_SSL_CLIENT_AUTH_CERT

------
cjhveal
Oh wow, at first I thought this was another ASCII-art to image generator like
ditaa[1]. This is much more practical.

I'll give this a shot next time I might have otherwise reached for Graphviz or
Lucidchart.

[1]: [http://ditaa.sourceforge.net/](http://ditaa.sourceforge.net/)

~~~
Lio
Not to knock Mermaid but the interesting thing about Markdown to my mind is
that it’s still readable in raw format.

By which I mean it looks like a well annotated ASCII text file rather than a
raw markup language in text.

Ditta looks like at least has the potential for that. If github had the
ability render Ditaa it would be brilliant.

I think the main problem is that you still need the right tooling to draw it
efficiently and Markdown doesn’t really require that. Eg editor plugins for
reflow and drawing/resizing boxes.

~~~
steveax
Mac only, but Monodraw is pretty cool:

[https://monodraw.helftone.com](https://monodraw.helftone.com)

~~~
jraph
Asciiflow is nice: [http://asciiflow.com/](http://asciiflow.com/)

------
pronoiac
I like this! I'd love it if Github rendered Mermaid diagrams in their
Markdown.

~~~
logiclabs
Gitlab.com supports Mermaid in markdown..
[https://docs.gitlab.com/ee/user/markdown.html#mermaid](https://docs.gitlab.com/ee/user/markdown.html#mermaid)

~~~
wooly_bully
I just found this feature in our installation at work. It's so much more
convenient than lucidcharts or Visio or really any GUI option.

~~~
sytse
Yes, we use it at GitLab and it has been a game changer in making sure
diagrams are open to contributions.

------
soulnothing
If you have a grafana stack this is great with their plugin.

[https://grafana.com/plugins/jdbranham-diagram-
panel](https://grafana.com/plugins/jdbranham-diagram-panel)

I was able to do architectural diagrams and post them as dashboards. Showing a
top-level metric, then make that block red on a thresh hold breach. It gave
not only a top-level view, but a performance over view as well.

An example would be the frontend web requests and average latency response, to
api request count and latency than the actual database backend. All as
separate blocks with individual metrics.

------
rmetzler
blockdiag [0] has several helpful types of text to diagram processors with
several output filetypes like svg and png. In particular I like nwdiag
(network diagrams), rackdiag (server rack layout) and packetdiag the most.

There is also an interactive web form [1] to try it out. You can switch
between the types of diagram in the top right dropdown.

[0] [http://blockdiag.com/en/](http://blockdiag.com/en/)

[1]
[http://interactive.blockdiag.com/nwdiag/](http://interactive.blockdiag.com/nwdiag/)

~~~
arca_vorago
I second blockdiag and it's variants. One of my half done side projects is an
automatic network scanner and mapper that is versions so you can walk back in
time on the network with netdiag. The only downside to me is the non gpl
license.

------
zapita
Protip: Gitbook has a Mermaid plugin, and they make for a sweet combination.

------
jwilk
What do you mean by "Markdown-like"?

~~~
coldtea
Plain ascii text with as few special characters as possible and simple line
oriented syntax.

~~~
renku
I think the main advantage of Markdown is that the source is equally readable
without having to run it through a processor.

I don't think this really applies to this Mermaid library. For a Markdown-like
I would expect more of an ASCII-art like input, which would look like the
rendered chart also in its ASCII form.

~~~
coldtea
> _I don 't think this really applies to this Mermaid library._

Well, it is easy to just read and understand what it talks about (as opposed
to some more opaque format) and only has the bare minimum annotations needed
beyond the text labels and node names.

> _For a Markdown-like I would expect more of an ASCII-art like input, which
> would look like the rendered chart also in its ASCII form_

I don't see much value in such a scheme (even though there does exist such a
program), because to produce (and later edit/update) the ASCII-art would be as
tiresome and evolved as producing the final graphic document.

I'd rather write e.g something like:

    
    
      label a = "start"
      label b = "end"
      a -> b
    

than draw 2 ascii art boxes, place the labels myself, and draw ascii art arrow
between them.

------
nablaoperator
There is also 'Markdown Preview Enhanced' for Atom and VS Code which can
render Mermaid.

[https://github.com/shd101wyy/markdown-preview-
enhanced](https://github.com/shd101wyy/markdown-preview-enhanced)

------
Lunatic666
Wow, that’s awesome, I was looking for something like this a while ago to
visualize a state machine. I ended up using graphviz, but I’ll have a look at
mermaid for presentations, my diagrams always look super embarrassing.

------
tomonocle
Does anyone know of something similar for architecture diagrams?

I've tried PlantUML's component mode ([http://plantuml.com/component-
diagram](http://plantuml.com/component-diagram)) but wondered whether there
were any other options out there, as being able to write maintain source-
controlled diagrams as code/text would make me very happy!

------
seanwilson
Why does the text for flowchart end lines with semicolons but the other
diagram types don't?

------
hnaccy
I'm waiting for TikZ on the web.

~~~
cben
Client-side is not really feasible (emscripten TeX has been done, but the
packages to load are just too huge...).

Server-side, [https://tex.s2cms.com/](https://tex.s2cms.com/) does a nice job
and outputs svg; [https://upmath.me/](https://upmath.me/) by same author is
markdown editor integrating it - see tikz examples there.

------
andrewmcwatters
This isn't markdown-like.

------
mkempe
This is wonderful. Just being able to generate (and modify) a sequence diagram
from a text description is worth hours of work.

