Mermaid: Generate Diagrams and Flowcharts with Markdown Like Syntax | Hacker News Reader

Mermaid: Generate Diagrams and Flowcharts with Markdown Like Syntax

github.com

292 pointsshubhamjain52 comments

Open articleView on HN

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

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

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

Echoing the other comments, draw.io is fantastic for making state diagrams. Easy to use and lots of features!

Looks great, is there any other syntax available for more elements than what I am seeing in the docs/example? Either way it looks like a good way to get the basic elements down before editing by hand.

Draw.io is amazing. Thank you for the work you put in it.

The rack diagram is pretty nifty. Too bad it doesn't have my Sun Fire T2000 in it, though :(

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/images/blog/lsm-find.jpeg

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

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

How does this compare to graphviz? (http://www.graphviz.org/)

They have a broadly similar syntax for directed graphs, but Mermaid also provides a simple syntax for drawing UML sequence or class diagrams. You can draw class diagrams with GraphViz, but it's comparatively kludgy [1].

[1]: http://www.ffnn.nl/pages/articles/media/uml-diagrams-using-g...

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 [2]

As a reference: graphs with TikZ: 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/ for automatic positioning.

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/

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

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

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

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!)

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

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

Check groff/mandoc .

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

or Fig2: https://www.dropbox.com/s/2ilceiaqorpg3gt/fighadjxasymetric....

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

[1]: https://pdfs.semanticscholar.org/20c2/b82eef0809df80a402f125...

[2]: https://zanran_storage.s3.amazonaws.com/www.science.uva.nl/C...

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

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

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.

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.

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.

This reminds me of PlantUML, http://plantuml.com/.

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)

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

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

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.

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

There are a few atom plugins that support this.

I'm using Markdown Preview Enhanced now: 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 which is for authoring mermaid documents.

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://github.com/jdoconnor/chrome-diagrammer

Reminds me of http://www.websequencediagrams.com, though that isn't open source.

http://www.lucidchart.com has similar functionality as well.

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

https://github.com/ianmiell/learn-git-the-hard-way/blob/mast...

very very handy!

Since then I found this: http://live.yworks.com/

which looks nice but haven't used in anger.

I was quite excited by this - I normally use 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.

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

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

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

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!

Here's another similar one: https://code2flow.com/app

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.

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.

Sequence: mscgen

Gantt: ?

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

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.

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.

Your confusing CDN with something else.

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

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

I use the standalone version of this 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.

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

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

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.

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

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

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

Nice. Live demo would be wonderful.

http://knsv.github.io/mermaid/live_editor/

Reply on news.ycombinator.com