Mermaid: Markdown-like generation of diagrams and flowcharts from text | Hacker News Reader

Mermaid: Markdown-like generation of diagrams and flowcharts from text

github.com

453 pointstomcam61 comments

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

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

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

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

The following code is pretty easy to hack:

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.

You might want to check out the Eclipse Layout Kernel. I don't know if it supports everything you listed but it does seem to make for some neater graphs.

https://www.eclipse.org/elk

What kind of algos do they use for this kind of thing? Are there any papers?

There is a whole field about this. Look up 'Graph Drawing'.

Styling-wise, you could edit the CSS of Mermaid to try to achieve the cleaner look the Google diagrams provide. That doesn't solve the path optimization though, but it's something.

You should also check out http://plantuml.com/ An online editor/renderer is available at http://planttext.com/

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

Wouldn't it?

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

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.

It seems to me, to be a really bad idea to generate "almost code" in order to be able to generate diagrams for "actual code" that you have to write.

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/

Very cool project.

Good find. This should be linked in the readme

graphviz http://www.graphviz.org/download/

also the DOT language has been around for ages.

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

Yeah, PlantUML is my go-to for sequence diagrams. I used to hate them until I discovered it, there's even a great VSCode plugin for real-time iteration.

It's not so great with other things but worth it for that alone.

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

There is an emscripten compiled graphviz already. Works fine.

Yea, I've used 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.

The Mermaid syntax looks quite similar to DOT. It's at least partially inspired I guess.

DOT is really messy for complex layout of nodes, and Graphviz to my knowledge doesn't have any layout options to produce straight angled edges between nodes.

I love Graphviz, but that space badly needs more competition.

Not that I don’t welcome competition, but you mean the “splines” attribute?

https://www.graphviz.org/doc/info/attrs.html#d:splines

Ah, I had never seen that before - I see it was added in 2010, shows how long it was since I looked at the Graphviz docs I guess. But even so the docs and screenshot shows it has plenty of problems unless it's improved substantially beyond what's on that page.

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.

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

http://www.drawexpress.com

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

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

It is supported by asciidoctor-diagram.

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

See also markdeep:

https://casual-effects.com/markdeep

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

It’s perfectly readable on a mobile phone for me?

Me neither, on desktop: ERR_BAD_SSL_CLIENT_AUTH_CERT

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/

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.

Mac only, but Monodraw is pretty cool:

https://monodraw.helftone.com

Asciiflow is nice: http://asciiflow.com/

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

Gitlab.com supports Mermaid in markdown.. https://docs.gitlab.com/ee/user/markdown.html#mermaid

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.

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

Wished they rendered latex as well.

GitLab renders math (via KaTeX iirc): https://docs.gitlab.com/ee/user/markdown.html#math

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

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.

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/

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

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.

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

What do you mean by "Markdown-like"?

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

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.

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

MarkDeep tries this, it doesn't quite work in my opinion:

https://casual-effects.com/markdeep/features.md.html#toc2

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

https://github.com/shd101wyy/markdown-preview-enhanced

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.

Does anyone know of something similar for architecture diagrams?

I've tried PlantUML's component mode (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!

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

I'm waiting for TikZ on the web.

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/ does a nice job and outputs svg; https://upmath.me/ by same author is markdown editor integrating it - see tikz examples there.

This isn't markdown-like.

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

Reply on news.ycombinator.com