Mermaid: Create diagrams and visualizations using text and code | Hacker News Reader

Mermaid: Create diagrams and visualizations using text and code

mermaid-js.github.io

349 pointstomduncalf73 comments

It's convenient that GitHub Markdown supports graphs natively, and I've used Mermaid there successfully. However, I was fairly disappointed with Mermaid itself; I found the syntax irregular and non-intuitive (the syntax for every different graph type feels like it was designed by different people working independently), the documentation was sparse (though it exists at all, so I'll give it points for that), and worst of all the error messages were atrociously cryptic and entirely unhelpful.

That said, I also found the default styling and layout of the generated graphs to be far more attractive than Graphviz/dot, though I'm not sure if that's attributable to Mermaid or GitHub.

Which is to say, altogether probably a step forward, but still lots of room for improvement. Please, start with the error messages!

Makes me think of how UML has so many subdialects for different diagram types.

(You are supposed to be able to bootstrap all of UML from the very simple EMOF vocabulary but I think there are a few small missing pieces that make it non-trivial)

> the syntax for every different graph type feels like it was designed by different people working independently

That's mostly an artifact of trying to create a DSL for wildly different types of graphs. A unified syntax that covers sequence diagrams, pie charts, class diagrams, and more probably wouldn't be that pleasant, so why even try. You'll see the same thing in PlantUML.

Mermaid is great for keeping simple diagrams in Markdown documents, and GitHub very recently started supporting it. Beats taking screenshots and uploading PNGs to the repo for sure!

For those using VS Code, this GitHub Markdown extension also renders mermaid: https://marketplace.visualstudio.com/items?itemName=bierner....

Notion also renders Mermaid code blocks inline which I've found really helpful.

Wow! You're right. That's amazing. Definitely going to start using this.

Unfortunately, GitHub doesn’t support it in their built-in pages Jekyll implementation.

True, but the workaround is to render the Mermaid in the browser.

See: https://news.ycombinator.com/item?id=31275371

I try to keep html and javascript out of the markdown as part of the whole point is to not make writers know that stuff. Many of the authors I work with aren’t web devs so I don’t want to ask them to copy and paste special code beyond what mermaid requires.

Instead I just use GitLab where it works great. This is just an example of GitHub being a bit behind but am hopeful that they’ll eventually come up to speed. Especially since they have it in their markdown preview.

Yes! If you're making a product for "pure" writers, I'm with you almost 100%.

That being said, Markdown has always included the ability to insert custom HTML, because Gruber wrote it to scratch his own itch. He didn't make Markdown to hide HTML from himself, he made it to do away with all the ceremony of angle brackets, which are a PITA to type and definitely make the result harder to read from source.

From a readability standpoint, I'd prefer:

  ```mermaid
    stateDiagram
      [*] --> start
      start --> zero : 0
      start --> one : 1
      one --> one : 0, 1
      zero --> [*]
      one --> [*]
  ```

to:

  <div class="mermaid">
    stateDiagram
      [*] --> start
      start --> zero : 0
      start --> one : 1
      one --> one : 0, 1
      zero --> [*]
      one --> [*]
  </div>

But I can deal with that. What discomforts me personally is the worry that something about the mermaid.js implementation will break in a future browser version.

Were I compiling to SVG or PNG as part of my build tooling, I would have a lot more trust that I could maintain a working toolchain in the future.

JM2C, YMMV, &c.

It's also supported in Azure Devops wikis

But bizarrely they chose to execute and render it from code blocks, rather than syntax-highlight it like it's an example, and use some other syntax for rendering.

For example, Latex-style formulae are usually written (for markdown renderers that support it, not GitHub) $inline$ or in $$-delimited blocks. But if you want to explain how to do that then you write `$inline$` or

    ```latex
    $$
    \foobar
    $$
    ```

And that formats it, it doesn't execute the 'latex' (or whatever) interpreter with the contents and render its output.

Why not draw.io/diagrams.net? That used SVG which it embeds in pngs so they always render faithfully, and can be edited online, in the desktop app or directly in VS Code via a plugin.

That has dramatically better support.

Because you can't create PRs against it with readable diffs or code-generate them etc?

Exactly (though a diagramming tool could implement PRs in the future)

What might be cool is a graphical editor that uses Mermaid as a file format.

Trying to create certain types of diagrams (e.g. sequence diagrams) in Draw.io is a huge PITA.

I love that GitHub and Notion both support mermaid.js now!!

I wrote a tutorial for mermaid.js that you all might like :)

It includes: * the most common use cases * syntax gotchas and mnemonics for remembering them * how to style the diagrams (similar to css) * options for editors (including online ones! https://mermaid.live rocks)

Casey's Mermaid.js tutorial: https://www.happyandeffective.com/blog/realtime-collaborativ...

---

I also wrote a tutorial for graphviz (which does not have GitHub or Notion support last I checked). I'm so proud of it -- it's the most starred graphviz tutorial on GitHub

Casey's Graphviz tutorial: https://github.com/caseywatts/graphviz-tutorial

As well as Obsidian: https://obsidian.md/ !

Obisidian has a nice variety of packages for linux (one of the best I've seen so far).

However they don't have the simplest one (a tar.gz archive where you run ./app.sh from bin folder). But at least they have AppImage.

Edit: they actually have the tar.gz option but only for arm64

I appreciate and used to use Mermaid for everything. I've since found PlantUML to be phenomenal. There were a few things I couldn't flat out do with mermaid that I can't recall since it's been a year. But I've never run into a limitation with PlantUML

For something a bit more user-friendly check out flowchart.fun [0] – I just interviewed the sole developer [1]

[0]: https://flowchart.fun/ [1]: https://sourcetarget.email/editions/43/

Interesting. Is there a way to run it from the command line?

Yep!

https://www.npmjs.com/package/flowchart-fun

I come from past experiments with (py)graphviz, yed, probably a couple other forgotten things. (As well as manual diagrams in LucidChart and even Inkscape.) And am generally a non-web python guy.

I was looking at Mermaid last weekend, since a coworker has praised it a few times and I was wanting to play with it.

I think my expectation of how to use it was wrong? I typically expect to share my diagrams as .png files. The main documentation didn't seem to give much guidance in this usecase.

I ended up going to https://github.com/mermaid-js/mermaid-cli ... there didn't seem to be a simple install-and-use pathway similar to `apt` or `pip`, so I ended up trying the docker image for it. I got it working to create pngs, but I thought having to mess with docker volume mounts and defining my own aliases (`alias mermaid='docker run -u $UID -it --rm -v ~/mermaid:/data minlag/mermaid-cli -i'` so I can do `mermaid blah.mmd` in my ~/mermaid folder) was a bit cumbersome...

Just sharing to see if there's hot takes on where I went wrong, I guess. (for example, I certainly didn't extensively read the docs to understand the usage paradigm it's intended for)

The whole point of Mermaid is _not_ having to embed .png's into your Markdown files.

By using the built-in codeblocks functionality of Markdown, Mermaid allows you to source-control the same exact graphs that you would have normally put in as images.

That was a piece of information I missed, then! Definitely a nice usecase to keep in mind.

For me, I'm often either (1) sharing diagrams outside of github (e.g. email), as well as (2) generating a bunch of diagrams based on code or whatever, rather than defining a diagram in a markdown file. There may be better tools for those usecases. Those were what I was trying to do last weekend, too.

But I've definitely passed on adding diagrams to my .md files, or sighed at needing to add yet another imgs/ dir and files to a repo folder. My toolbelt now has another thing hanging off it!

At the cost of constraining the rendering environment, do I get that right?

So the desire "Turn this generated graph into a diagram for inclusion in this PDF report" would be deemed a category error: my desire is wrong.

It clearly makes some folks happy, but to me it's the antithesis of a "tool"; it's more a "website feature". Different strokes.

I write my .pdfs in a stand-alone markdown editor which supports mermaid, so your use-case is what I experience when doing graphs in writing.

This way, there's no need to separately generate an image output to include into the document later on.

Different "tools".

That said, I'd love a dedicated application for diagraming, with exports to various formats for other use-cases.

I made PNGs to share because Github Enterprise doesn't display Mermaid as images yet, and the diagram was more than one page so I couldn't screenshot. I used Mermaid CLI, which brings along chromium and puppeteer to render images:

    npm i mermaid.cli
    npm i mermaid
    npm i puppeteer@latest
    ./node_modules/.bin/mmdc -i my_diagram.md -o my_image_name.png

Only problem was the text overhangs the bubbles in sequence diagram notes.

I use a VS Code extension and the Live Editor:

https://mermaid.live

I’m such a huge fan of mermaid and use it in all my architecture markdown sites.

I was excited when GitHub enabled mermaid in their markdown preview. But weird that they still don’t support it in GitHub pages. I wish they would do this as being able to use mermaid in the default pages sites will be really nice. I’m currently not able to convince scientists I work with to set up their own static site generation instead of pages, just to get mermaid working.

Mermaid is useful for small diagrams with a few elements.

When I try to create large diagrams with lots of linkages and text, my laptop fans kick in, and the battery starts draining. I use a reasonably beefy macbook pro as my daily driver.

How large are the diagrams you’re trying to create?

What are you viewing the diagrams in? Maybe the problem is more with it than Mermaid?

One thing I didn't see mentioned here is that mermaid makes creating charts programmatically very simple. We have a ton of workflows that are basically FSAs. We use Mermaid to create visuals of the workflows on the fly. Change it in code and the docs auto update.

Also, VisualStudio.com supports Mermaid as well.

A few times a team member has tried to get everyone on board with Mermaid.

In the end draw.io/diagrams.net wins out as embeds the diagram in the header of a PNG, so it can be rendered by everything and edited in many ways, including the web, the desktop app or the VS Code plug in.

Interested Emacs users should check out ob-mermaid[1]. It’s an org babel extension that lets you inline mermaid diagrams in org documents.

[1] https://github.com/arnm/ob-mermaid

I made a fun chart tracing energy from the Big Bang to modern primary sources in Mermaid JS because it was so fun and easy. [1]

Then a guy on twitter and his son remixed it graphically into something truly artistic. [2]

I thank Mermaid for the overall experience b/c it let somewhat complex concepts be shown so clearly that they could be immediately understood.

[1] https://whatisnuclear.com/energy-flow.html

[2] https://i.imgur.com/SJjRaGH.jpg

Mermaid is particularly easy to embed in online web pages. Naturally, the most robust thing to do is generate a .png and embed that. But if you write in Markdown and have a rendering tool that directly supports Mermaid, you can add your Mermaid directly to the Markdown source that you check into git.

And even if you don't have direct tooling support for Mermaid, you can render it in the browser using JavaScript. For example:

https://raganwald.com/2019/09/21/regular-expressions.html#fi...

The markdown is:

  # Finite-State Recognizers

  If we're going to compile regular expressions to finite-state
  recognizers, we need a representation for finite-state recognizers.
  There are many ways to notate finite-state automata. For example, state
  diagrams are particularly easy to read for smallish examples:


  <div class="mermaid">
    stateDiagram
      [*] --> start
      start --> zero : 0
      start --> one : 1
      one --> one : 0, 1
      zero --> [*]
      one --> [*]
  </div>

  Of course, diagrams are not particularly easy to work with in
  JavaScript. If we want to write JavaScript algorithms that operate on
  finite-state recognizers, we need a language for describing finite-state
  recognizers that JavaScript is comfortable manipulating.

IMO, the best way to use it is within a format you're already checking into git, and if you can, use a tool that compiles your diagrams into an embedded SVG at rendering time.

But even if your toolchain doesn't make this easy, it's still flexible enough to get the job done.

Unfortunately, Mermaid can’t render to SVG without a full browser rendering engine. This was my biggest complaint about Mermaid.

There is a command line tool, but it downloads a browser renderer.

Hopefully someone will let me know if this has changed since I looked :)

True. In my case, I'm using Github's built-in Jekyll implementation, and I prefer to keep it as bog-standard as possible, so I went with in-browser rendering. I expect that one day many years hence, something will break and my diagrams will stop working.

One day, I should sit down and manually render them all to .png and update the markdown to use the .pngs instead. But today is not that day. Tomorrow isn't looking too good, either.

It has not!

I hit this problem when trying to integrate Mermaid into a Swift Package Manager build tool. SPM sandboxes build tool access to specific folders and this causes the headless Chromium used by Mermaid-CLI to blow up.

I'm currently evaluating whether to decouple Mermaid from the browser by using a minimal fake DOM, or just rewriting it in pure Swift. It would be nice if DocC could support Mermaid in Swift doc comments.

Shameless plug, but I used mermaid.js to create a pom visualizer maven plugin [0] and it was honestly pretty great.

Like some of the other comments say (and after working with it quite a bit) it definitely has its warts. It's not super well documented, it's not as feature rich as I'd like, and the syntax can be a little wonky. All that said, it "just works" for creating simple visualizations and fit my use case near perfectly.

[0]: https://github.com/floverfelt/pom-visualizer-maven-plugin

I use Mermaid every week or so, it’s very cool.

It’s choices on where to position things are often infuriating but every visual flowchart builder has been a huge pain IMO so a text based one is super preferable even with the limitations.

I'm pretty obsessed with diagrams as code and unfortunately while I liked the visuals produced by Mermaid I found some major limitations with it on my last comparison test a few months ago. I think it might just need to mature a little bit and then will probably be a solid choice. More of a greybeard sysadmin thing, but I usually refuse to install npm things locally so thats another issue for others who feel the same.

What I use myself and suggest to others these days is first and foremost blockdiag and its variants (nwdiag, seqdiag, rackdiag, etc), and the very descriptive python "diagrams".

Is there any way to embed diagrams in code comments and have it render in any IDE or source code hosting platform?

Am I wrong for wanting this?

As in "ASCII art"?

Generalized to "Unicode art" input, with smoothed output in SVG format:

https://github.com/blampe/goat

That's interesting.

I was thinking something like this:

println 'hello world';

/* #mermaid graph TD; A-->B; A-->C; B-->D; C-->D; */

When the file is viewed in the IDE or git web host the image is rendered in the text viewer.

as a related piece of new of today [0]:

> The @github Markdown Preview extension for VS Code now includes Mermaid support!

and since Nim also made front page today I will share how I added mermaid.js support in my very own nimib project some time ago [1].

[0]: https://twitter.com/mattbierner/status/1522003140777701376 [1]: https://pietroppeter.github.io/nblog/drafts/mermaid_diagram....

My first contact with Mermaid was in Typora, and it always worked well enough for me.

Typora is awesome, and the support for different markdown extensions is great. I love it.

Github has the best Markdown implementation I've ever seen.

Looking forward to this being available in more places, I'll probably start using it in my documentation.

Anyone know if Activity diagrams can be made in this way? (Note activity diagrams are not exactly flow charts, they have some rules)

I think mermaid also has activity diagrams. You may find a tool for your need in this list https://xosh.org/text-to-diagram/

Mermaid (and plantUML) are great for simple diagrams. They aren't model-based though, so sharing resources across many views isn't possible. If you are looking for something more robust, consider something model-based like Ilograph: https://app.ilograph.com/demo.ilograph.AWS%2520Distributed-L...

Ilograph looks interesting, however seems more complex than mermaid

Certainly. It's definitely less quick-and-dirty and more focused on long-term value.

Elixir's ex-doc lets you embed Mermaid directly, and generate it on the fly through a function.

How would this be different from plantuml?

It has less features and less ablity to control the diagram than plantUML, but it is supported out of the box in a number of locations. Gitlab and now github.

Is anyone working on adding Mermaid support to Swift's DocC ?

earnest question; why would I use this instead of graphviz?

I used it to embed graphs in a single markdown document, as such quite useful.

It's the markup language supported by GitLab MR and Wiki; that was my first contact with it: https://docs.gitlab.com/ee/user/markdown.html#mermaid

According to a top-level comment, GitHub also supports it, too, now: https://docs.github.com/en/get-started/writing-on-github/wor...

The syntax is much simpler (albeit less powerful). It's suited to include in a markdown document where you don't know if the recipient is able to parse mermaid diagrams and ensure they get something readable.

I've used Graphviz for a long time and is still my first port of call where I need to produce the graph as a SVG or PNG.

However, if I'm putting the graph into a project in GitHub/GitLab then I'll use Mermaid as it lets me keep it inline in the markdown file itself. It's also makes it easier for other team members to maintain that graph in the documentation as it doesn't require them to run additional tooling.

mermaid (and similar diagrams-as-text tools) have a higher level of abstraction so they're quicker when you need something they're targeting.

Also: graphviz is good at graphs, but not every visual representation is a graph (e.g. sequence diagrams, railroad diagrams, gantt charts).

I learned about this last week and I am so impressed.

still no topological charts though:(

What is a topological chart?

Lets say a bunch of servers and how they communicate

There are Go and Python based packages for diagrams as well:

https://diagrams.mingrammer.com/ https://github.com/blushft/go-diagrams

Reply on news.ycombinator.com