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!
> 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.
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)
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!
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.
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.
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)
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
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
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!
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’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.
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.
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.
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:
# 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.
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.
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.
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".
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...
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.
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.
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.
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!