
Mermaid: Generate Diagrams and Flowcharts with Markdown Like Syntax - shubhamjain
https://github.com/knsv/mermaid
======
davidjgraph
draw.io [1] has this hidden under Arrange->Insert->From Text and is also open
source [2]. I work on the project.

[1] [https://www.draw.io](https://www.draw.io)

[2] [https://github.com/jgraph/draw.io](https://github.com/jgraph/draw.io)

~~~
davecap1
draw.io is awesome! Thanks for the hard work!

------
jankotek
I had problem with diagrams for my blog. Graphviz and similar tools did not
really worked for me.

Best solution for me was to take pencils and scanner:

[http://www.mapdb.org/blog/lsm_store_and_updates/](http://www.mapdb.org/blog/lsm_store_and_updates/)

[http://www.mapdb.org/images/blog/lsm-
find.jpeg](http://www.mapdb.org/images/blog/lsm-find.jpeg)

~~~
closed
I really like hand drawn graphs in articles like these, but couldn't say
whether it's because they're drawn by hand, or whether computer generated
graphs are often much harder to get "right".

~~~
jankotek
Thanks, I found it very difficult to express my ideas in computer generated
chart.

------
praveenster
How does this compare to graphviz?
([http://www.graphviz.org/](http://www.graphviz.org/))

~~~
WorldMaker
The big difference is it's built from the start with web tech.

Looking at it, my biggest criticism is that I would appreciate it more if it
did share/piggyback more with graphviz's DOT language. [1]

If it could import/export DOT files it would make it easier to do things like
start with Mermaid and migrate to Viz.js or graphviz itself (on a server
backend somewhere) if you find for a particular graph you might need different
performance characteristics or to use one of graphviz's alternate layout
engines (such as a neato or twopi).

(I could especially see a use if it could manage to export its more domain-
specific sequence and class diagram formats to "traditional" graphviz
digraphs. Nearly all of that formatting is possible with enough work with
digraphs in DOT language, but it's not a pleasure to build by hand and a DSL
convertable to it would actually be generally useful, I would imagine.)

[1]
[https://github.com/knsv/mermaid/issues/5](https://github.com/knsv/mermaid/issues/5)
[2]

------
stared
As a reference: graphs with TikZ:
[http://www.texample.net/tikz/examples/tag/graphs/](http://www.texample.net/tikz/examples/tag/graphs/)

Also a easy-to-write (and read!) syntax, but so much more powerful.

See also:
[https://www.overleaf.com/6471895cgxfsd#/21846512/](https://www.overleaf.com/6471895cgxfsd#/21846512/)
for automatic positioning.

~~~
jamessb
The examples showing TikZ used to draw a sequence diagram [1, 2] or class
diagram [3] are _far_ more verbose than the examples in the mermaid readme
[4], so mermaid looks easier to write.

[1]: [http://www.texample.net/tikz/examples/pgf-
umlsd/](http://www.texample.net/tikz/examples/pgf-umlsd/)

[2]: [http://www.texample.net/tikz/examples/sequence-
diagram/](http://www.texample.net/tikz/examples/sequence-diagram/)

[3]: [http://www.texample.net/tikz/examples/class-
diagram/](http://www.texample.net/tikz/examples/class-diagram/)

[4]: [https://github.com/knsv/mermaid](https://github.com/knsv/mermaid)

~~~
stared
In LaTeX things can be extremely verbose in general. But for TikZ it is easy
to do one note or edge per line.

Sure, mermaid looks even more compact, but at a huge price of flexibility.
(Don't take me wrong - for sure it has its use-cases!)

------
rixed
I miss pic so much. It is a macro processor for troff, that is not used so
much any more and for good reasons. But pic was amazing, so simple and yet so
powerful. Probably the ancestor of all including tikz.

Link:
[https://en.m.wikipedia.org/wiki/Pic_language](https://en.m.wikipedia.org/wiki/Pic_language)

In which I just learnt that there exists a stand alone version that produces
svg:
[https://ece.uwaterloo.ca/~aplevich/dpic/](https://ece.uwaterloo.ca/~aplevich/dpic/)

~~~
Jugurtha
I've only discovered pic when it got mentioned in a previous thread (there was
a Show HN for something called Code2Flow if my memory serves me well). I first
thought it was about the Intel 8259 (Programmable Interrupt Controller) or
Microchip's uControllers.

As for tikz, I've used pgfplot and tickz + matlab2tikz[0] to produce TeX PDFs
from MATLAB figures (it can only export figures as raster or MATLAB .fig,
unusable elsewhere), and include those in a bigger PDF (given the number of
figures, they had to be generated separately and then included because the
memory usage was just too high).

It gives something like Fig1:
[https://www.dropbox.com/s/m9ah60u89jjpcx7/fighadjxusefulclea...](https://www.dropbox.com/s/m9ah60u89jjpcx7/fighadjxusefulcleanaokstock.pdf?dl=0)

or Fig2:
[https://www.dropbox.com/s/2ilceiaqorpg3gt/fighadjxasymetric....](https://www.dropbox.com/s/2ilceiaqorpg3gt/fighadjxasymetric.pdf?dl=0)

Fig1: Upper is a cleaned ECG signal. Middle is a Time-Frequency representation
using an "Adaptive Optimal Kernel"[1]. Bottom is a Time-Frequency
representation using Stockwell Transform. They look gorgeous embedded and you
can _zoom_ , contrary to MATLAB PNGs.

Fig2: baseline estimation using asymmetric least squares[2] (they used it to
clean [spectro/chromato]graphy graphs and I tried it on ECG. It's really
cool).

[0]:
[https://www.mathworks.com/matlabcentral/fileexchange/22022-m...](https://www.mathworks.com/matlabcentral/fileexchange/22022-matlab2tikz-
matlab2tikz)

[1]:
[https://pdfs.semanticscholar.org/20c2/b82eef0809df80a402f125...](https://pdfs.semanticscholar.org/20c2/b82eef0809df80a402f12589e78c6a58ed65.pdf)

[2]:
[https://zanran_storage.s3.amazonaws.com/www.science.uva.nl/C...](https://zanran_storage.s3.amazonaws.com/www.science.uva.nl/ContentPages/443199618.pdf)

------
lobster_johnson
I suspect this was posted because I linked it in a comment in a different
thread yesterday [1].

Mermaid is a great tool, especially for flowcharts. But as with other tools
like Graphviz, it can be hard/impossible to build a clean _structural_
diagram, where you have nodes that contain or stack other nodes, with flows
and relationships between them. Invariably, I find that tools like Mermaid
break down once there's a lot of components, even when using boxes and so on
to group things.

In particular, arrow routing is a weak point. Here [2] is an old diagram I
once did in Mermaid. I was able to create two vertically-layered groups, but I
was not able to prevent arrows from being messy. (There is, of course, one
pair of arrows that need to cross in that diagram, but at least the software
should be able to draw their intersection in a nicer way, e.g. by adding space
around the arrow or have a little arch where one arrow jumps over the other.)

[1]
[https://news.ycombinator.com/item?id=13324796](https://news.ycombinator.com/item?id=13324796)

[2] [http://i.imgur.com/awunH4m.png](http://i.imgur.com/awunH4m.png)

~~~
ioloop
I feel ya. But remember your users probably don't care. You are trying to
convey information, and your diagram does so effectively. Everything else is
sugar. But if you are dissatisfied then you could also take a look at
code2flow.com which is very quick and easy to use. I'd be quite curious if it
solves your issue. I suspect it will.

~~~
lobster_johnson
Eh, the point is avoid unnecessary work. If you have just one diagram,
creating it by hand is not a problem. If you have 10 or 20, you want
automation. Especially since you'll want to keep the diagram continually
updated, maybe tweakable with different styles; editing all diagrams by hand
every time for every colour change is arduous compared to just running a
single command to re-render.

------
ecesena
I love the simplicity of tools like mermaid.

For complex drawings, especially graphs, I think one missing piece (in tikz
and others) is to distinguish the structure vs the positioning/coloring, more
or less like html and css do.

Often time a complex graph in auto generated (structure) plus manually
adjusted to make it nicer (pos & colors), and it would be great to have these
two pieces clearly separated for iterating faster.

------
LaSombra
This reminds me of PlantUML, [http://plantuml.com/](http://plantuml.com/).

~~~
yoz-y
Very much so, I have tried to paste in some more complex sequence diagrams I
have written and they almost work. Except no aliases and no on the fly
creation/destruction of participants. (or maybe the syntax is different)

I would prefer if this actually followed the plantuml syntax exactly, that way
one could ditch the official java application which is quite bad (and graphs
are quite ugly)

~~~
stuart78
Totally agree. Plant handles many complexities quite nicely, despite the poor
tools available to render the visualization.

------
TuringTest
There's also DRAKON Editor. [1] While it's visual and does not have a text
markdown form, it provides rules to achieve arbitrarily large readable flow
diagrams, and enforces them semi-automatically.

[1]
[https://en.wikipedia.org/wiki/DRAKON](https://en.wikipedia.org/wiki/DRAKON)

~~~
tnorthcutt
I've been fascinated by DRAKON since I first read about it a few years ago. I
don't really have a reason to use it, but for some reason it just seems
awesome that a programming language produced by the Russian Space agency is
now open source.

 _DRAKON is an algorithmic visual programming language developed within the
Buran space project following ergonomic design principles. The language
provides a uniform way to represent flowcharts of any complexity that are easy
to read and understand.

The DRAKON Editor, which was released in September 2011, is an implementation
of the language available in the public domain. It can be used for creating
documentation, or for creating visual programs that can be converted to source
code in other languages._

------
homarp
Can it generate interactive graphs like the one on
[https://onesignal.com/blog/rust-at-
onesignal/](https://onesignal.com/blog/rust-at-onesignal/) ?

------
crucialfelix
There are a few atom plugins that support this.

I'm using Markdown Preview Enhanced now: [https://atom.io/packages/markdown-
preview-enhanced](https://atom.io/packages/markdown-preview-enhanced)

with which you can embed mermaid sketches into normal markdown documents. This
is perfect for most use cases where you want a simple diagram inside a text
document.

Also atom-mermaid: [https://atom.io/packages/atom-
mermaid](https://atom.io/packages/atom-mermaid) which is for authoring mermaid
documents.

~~~
jdoconnor
I use mermaid and flowchart in github readmes using an extension for chrome.
The basic idea is that the libraries are part of the extension, and the
markdown calls out what kind of diagram it is.

chrome store: [https://chrome.google.com/webstore/detail/chrome-
diagrammer/...](https://chrome.google.com/webstore/detail/chrome-
diagrammer/bkpbgjmkomfoakfklcjeoegkklgjnnpk)

[https://github.com/jdoconnor/chrome-
diagrammer](https://github.com/jdoconnor/chrome-diagrammer)

------
feistypharit
Reminds me of
[http://www.websequencediagrams.com](http://www.websequencediagrams.com),
though that isn't open source.

~~~
dmgrow
[http://www.lucidchart.com](http://www.lucidchart.com) has similar
functionality as well.

------
zwischenzug
Came across this a while ago, and used extensively for this:

[https://github.com/ianmiell/learn-git-the-hard-
way/blob/mast...](https://github.com/ianmiell/learn-git-the-hard-
way/blob/master/README.md)

very very handy!

Since then I found this: [http://live.yworks.com/](http://live.yworks.com/)

which looks nice but haven't used in anger.

------
maffydub
I was quite excited by this - I normally use mscgen
([http://www.mcternan.me.uk/mscgen/](http://www.mcternan.me.uk/mscgen/)).

Unfortunately, I can't find a way to break text strings onto multiple lines in
ladder diagrams. Does anyone know how?

One of the examples shows <br/> tags within a Note. The <br/> is stripped out
and the text is wrapped onto multiple lines within the note box, but the
wrapping is completely independent of the <br/> tags.

...and this doesn't work for text on ladder diagram arrows. I find this very
useful to add additional information, e.g. "POST /echo" above the arrow and
the POST body below the arrow.

~~~
sverweij
Use '\n' for line breaks, like so:

a => b [label="POST /echo\nHello, it's me"];

(You might like [https://mscgen.js.org](https://mscgen.js.org) b.t.w.)

~~~
maffydub
Sorry, I meant I couldn't find a way to do the same thing as that in Mermaid -
I realize my message wasn't very clear, but thanks for replying!

------
xt508
Here's another similar one:
[https://code2flow.com/app](https://code2flow.com/app)

------
dkural
The documentation site, including the rendering of the page, the accordion
menu on the left, and the diagram renderings look a bit buggy and jumbled to
me. Would be awesome to use a better solution for documentation. The accordion
navigation keeps closing before I can click, clicks don't work etc.

------
vladsanchez
I was trying to make Graphviz produce all these types of charts using a
Markdown DSL for version-control purposes, but like some said, it's kludgy.

I'm mostly interested in a tool that can produce Flowchart, Sequence, Gantt,
Dataflow, Class and Database diagrams using nothing but a CLI.

I'd appreciate any recommendations.

~~~
contingencies
Sequence: mscgen

Gantt: ?

Flowchart, dataflow, class, database: graphviz (eg.
[https://github.com/globalcitizen/mysqlviz](https://github.com/globalcitizen/mysqlviz))

------
kmfrk
Word of advice: name your .js file after its versioning (or use ?v=x.y.z in
the src), because some updates break older code.

I had to go through all the versions at one point to make my old code work
again, because I'd used a remote CDN or something at one point.

Excellent tool otherwise, haven't seen anything better so far.

~~~
WorldMaker
I disagree: version management of that source is not the job of the JS file
but the CDN and/or package manager (npm, jspm, what have you). If the CDN you
had been using did not provide a way to version the JS you retrieve from it, I
would suggest you look for a better CDN.

I can't say that I've even seen a CDN without versioning support; the closest
I've seen is that some READMEs for GitHub packages will suggest the RawGit CDN
that reflects the GitHub namespace and point to something like the master
branch instead of a version tag. I've sent a PR to correct at least one of
those that I had come across, but it's also something to realize that if you
are using a CDN like RawGit, check the tag/branch you are using.

~~~
user5994461
Your confusing CDN with something else.

A CDN doesn't do versioning support, it serves files and respect the caching
headers it was given.

~~~
WorldMaker
Sure it's not often considered a part of the definition of a CDN, but version
management very much is the duty of a good CDN (even just as a part of cache
management to know when to clear/refresh caches).

A CDN built for public usage (ie, that you do not run yourself DIY style, and
isn't a corporate internal CDN they don't expect outsiders to reuse) that is
built to serve JS (and often CSS, too) will through necessity provide some
versioning mechanism. As I said, if you find a CDN that is serving JS files
and doesn't have some sort of versioning mechanism or policy in place then you
find a better CDN. I think at this point good versions strategies is a
requirement for a good CDN.

Take MaxCDN as a good example since it is one of the most common CDNs at this
point for JS/CSS (Bootstrap, Font Awesome, Twemoji, ...): all of their URLs
have version numbers in their path structure (/bootstrap/3.3.7/...).

RawGit is probably the next most common I see, thanks to it making it very
easy for anyone to CDN access a GitHub repo. As I mentioned before: RawGit
uses git branches and tags in its folder structure for version management. If
you are using a RawGit URL with /master/ in the URL you should switch to a
version tag pronto (and that's not RawGit's fault, it's yours for giving it a
floating version requirement).

------
AstroJetson
I use the standalone version of this
[https://www.websequencediagrams.com/](https://www.websequencediagrams.com/)
and I love it. Simple to use, different formats, I can map complex stuff into
a easy peasy picture.

Highly recommended.

------
kevinastone
Seems very similar to blockdiag[0] which works well with Sphinx documentation.

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

------
unit91
Great work! Really excited to see something that's easy, pretty, and open
source. All the alternatives mentioned here are lacking at least one of those
areas. Thanks for sharing.

------
nopzor
mermaid seems really cool. i first got turned on to it when jdbranham created
a diagram plugin for grafana, based on mermaid.

if you're using grafana, it allows you to generate mermaid-powered diagrams
powered from your tsdb.

check it out: [https://grafana.net/plugins/jdbranham-diagram-
panel](https://grafana.net/plugins/jdbranham-diagram-panel)

------
andrewingram
I've been using this for a while, it's quite nice. There are some editor
plugins for it too (of varying usefulness).

------
eutropia
How much work would it be to turn this into an electron app... or is this a
stupid question? (not a web dev)

------
asimjalis
Nice. Live demo would be wonderful.

~~~
rubyfan
[http://knsv.github.io/mermaid/live_editor/](http://knsv.github.io/mermaid/live_editor/)

