9 ms·

Mermaid: Create diagrams and visualizations using text and code

349 points by tomduncalf 4y ago

oicU00 4y ago
There are Go and Python based packages for diagrams as well: https://diagrams.mingrammer.com/ https://diagrams.mingrammer.com/ https://github.com/blushft/go-diagrams https://github.com/blushft/go-diagrams
arbitrage 4y ago
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.
- anoncept 4y ago
  How large are the diagrams you’re trying to create?
  - corn13read 4y ago
- tclancy 4y ago
  What are you viewing the diagrams in? Maybe the problem is more with it than Mermaid?
macgyverismo 4y ago
earnest question; why would I use this instead of graphviz?
- nxpnsv 4y ago
  I used it to embed graphs in a single markdown document, as such quite useful.
- mdaniel 4y ago
  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 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/working-with-advanced-formatting/creating-diagrams https://docs.github.com/en/get-started/writing-on-github/wor...
- bzxcvbn 4y ago
  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.
- scrapheap 4y ago
  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.
- sverweij 4y ago
  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).
gepeto42 4y ago
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.markdown-preview-github-styles https://marketplace.visualstudio.com/items?itemName=bierner....
- rockostrich 4y ago
  Notion also renders Mermaid code blocks inline which I've found really helpful.
  - spiderice 4y ago
    Wow! You're right. That's amazing. Definitely going to start using this.
- prepend 4y ago
  Unfortunately, GitHub doesn’t support it in their built-in pages Jekyll implementation.
  - a4isms 4y ago
    True, but the workaround is to render the Mermaid in the browser. See: https://news.ycombinator.com/item?id=31275371 https://news.ycombinator.com/item?id=31275371
    - prepend 4y ago
      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.
jedimastert 4y ago
My first contact with Mermaid was in Typora, and it always worked well enough for me.
- doctor_eval 4y ago
  Typora is awesome, and the support for different markdown extensions is great. I love it.
pietroppeter 4y ago
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 https://twitter.com/mattbierner/status/1522003140777701376 [1]: https://pietroppeter.github.io/nblog/drafts/mermaid_diagram.html https://pietroppeter.github.io/nblog/drafts/mermaid_diagram....
prepend 4y ago
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.
gertlex 4y ago
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 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)
- fbrchps 4y ago
  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.
  - gertlex 4y ago
    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!
  - rout39574 4y ago
    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.
eptcyka 4y ago
How would this be different from plantuml?
- ldiracdelta 4y ago
  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.
a4isms 4y ago
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#finite-state-recognizers-1 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.
- schemescape 4y ago
  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 :)
  - sodality2 4y ago
    It has not!
  - a4isms 4y ago
    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.
User23 4y ago
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 https://github.com/arnm/ob-mermaid
fallingmeat 4y ago
Anyone know if Activity diagrams can be made in this way? (Note activity diagrams are not exactly flow charts, they have some rules)
- smusamashah 4y ago
  I think mermaid also has activity diagrams. You may find a tool for your need in this list https://xosh.org/text-to-diagram/ https://xosh.org/text-to-diagram/
99_00 4y ago
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?
- dmullis 4y ago
  As in "ASCII art"? Generalized to "Unicode art" input, with smoothed output in SVG format: https://github.com/blampe/goat https://github.com/blampe/goat
  - 99_00 4y ago
    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.
kibwen 4y ago
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!
- PaulHoule 4y ago
  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)
- xienze 4y ago
  > 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.
aliswe 4y ago
still no topological charts though:(
- xamde 4y ago
  What is a topological chart?
  - aliswe 4y ago
    Lets say a bunch of servers and how they communicate
heycaseywattsup 4y ago
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 https://mermaid.live rocks) Casey's Mermaid.js tutorial: https://www.happyandeffective.com/blog/realtime-collaborative-diagramming-in-notion-with-mermaidjs 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 https://github.com/caseywatts/graphviz-tutorial
- sleight42 4y ago
  As well as Obsidian: https://obsidian.md/ https://obsidian.md/ !
  - arein3 4y ago
    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
tamiral 4y ago
I learned about this last week and I am so impressed.
nickmain 4y ago
Is anyone working on adding Mermaid support to Swift's DocC ?
Veuxdo 4y ago
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-Load-Testing/__overview https://app.ilograph.com/demo.ilograph.AWS%2520Distributed-L...
- arein3 4y ago
  Ilograph looks interesting, however seems more complex than mermaid
  - Veuxdo 4y ago
    Certainly. It's definitely less quick-and-dirty and more focused on long-term value.
happymellon 4y ago
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.
shafoshaf 4y ago
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.
amingilani 4y ago
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
arminiusreturns 4y ago
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".
cjlm 4y ago
For something a bit more user-friendly check out flowchart.fun [0] – I just interviewed the sole developer [1] [0]: https://flowchart.fun/ https://flowchart.fun/ [1]: https://sourcetarget.email/editions/43/ https://sourcetarget.email/editions/43/
- asimjalis 4y ago
  Interesting. Is there a way to run it from the command line?
  - cjlm 4y ago
    Yep! https://www.npmjs.com/package/flowchart-fun https://www.npmjs.com/package/flowchart-fun
tehwebguy 4y ago
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.
floverfelt 4y ago
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 https://github.com/floverfelt/pom-visualizer-maven-plugin
acidburnNSA 4y ago
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 https://whatisnuclear.com/energy-flow.html [2] https://i.imgur.com/SJjRaGH.jpg https://i.imgur.com/SJjRaGH.jpg
kimi 4y ago
Elixir's ex-doc lets you embed Mermaid directly, and generate it on the fly through a function.
eternityforest 4y ago
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.

349 points by tomduncalf 4y ago

There are Go and Python based packages for diagrams as well: https://diagrams.mingrammer.com/ https://diagrams.mingrammer.com/ https://github.com/blushft/go-diagrams https://github.com/blushft/go-diagrams

arbitrage 4y ago

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.

anoncept 4y ago
How large are the diagrams you’re trying to create?
- corn13read 4y ago
tclancy 4y ago
What are you viewing the diagrams in? Maybe the problem is more with it than Mermaid?

macgyverismo 4y ago

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

nxpnsv 4y ago
I used it to embed graphs in a single markdown document, as such quite useful.
mdaniel 4y ago
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 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/working-with-advanced-formatting/creating-diagrams https://docs.github.com/en/get-started/writing-on-github/wor...
bzxcvbn 4y ago
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.
scrapheap 4y ago
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.
sverweij 4y ago
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).

gepeto42 4y ago

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.markdown-preview-github-styles https://marketplace.visualstudio.com/items?itemName=bierner....

rockostrich 4y ago
Notion also renders Mermaid code blocks inline which I've found really helpful.
- spiderice 4y ago
  Wow! You're right. That's amazing. Definitely going to start using this.
prepend 4y ago
Unfortunately, GitHub doesn’t support it in their built-in pages Jekyll implementation.
- a4isms 4y ago
  True, but the workaround is to render the Mermaid in the browser. See: https://news.ycombinator.com/item?id=31275371 https://news.ycombinator.com/item?id=31275371
  - prepend 4y ago
    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.

jedimastert 4y ago

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

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

pietroppeter 4y ago

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 https://twitter.com/mattbierner/status/1522003140777701376 [1]: https://pietroppeter.github.io/nblog/drafts/mermaid_diagram.html https://pietroppeter.github.io/nblog/drafts/mermaid_diagram....

prepend 4y ago

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.

gertlex 4y ago

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

fbrchps 4y ago
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.
- gertlex 4y ago
  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!
- rout39574 4y ago
  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.

eptcyka 4y ago

How would this be different from plantuml?

ldiracdelta 4y ago
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.

a4isms 4y ago

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#finite-state-recognizers-1 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.

schemescape 4y ago
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 :)
- sodality2 4y ago
  It has not!
- a4isms 4y ago
  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.

User23 4y ago

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 https://github.com/arnm/ob-mermaid

fallingmeat 4y ago

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

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

99_00 4y ago

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?

dmullis 4y ago
As in "ASCII art"? Generalized to "Unicode art" input, with smoothed output in SVG format: https://github.com/blampe/goat https://github.com/blampe/goat
- 99_00 4y ago
  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.

kibwen 4y ago

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!

PaulHoule 4y ago
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)
xienze 4y ago
> 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.

aliswe 4y ago

still no topological charts though:(

xamde 4y ago
What is a topological chart?
- aliswe 4y ago
  Lets say a bunch of servers and how they communicate

heycaseywattsup 4y ago

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 https://mermaid.live rocks) Casey's Mermaid.js tutorial: https://www.happyandeffective.com/blog/realtime-collaborative-diagramming-in-notion-with-mermaidjs 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 https://github.com/caseywatts/graphviz-tutorial

sleight42 4y ago
As well as Obsidian: https://obsidian.md/ https://obsidian.md/ !
- arein3 4y ago
  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

tamiral 4y ago

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

nickmain 4y ago

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

Veuxdo 4y ago

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-Load-Testing/__overview https://app.ilograph.com/demo.ilograph.AWS%2520Distributed-L...

arein3 4y ago
Ilograph looks interesting, however seems more complex than mermaid
- Veuxdo 4y ago
  Certainly. It's definitely less quick-and-dirty and more focused on long-term value.

happymellon 4y ago

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.

shafoshaf 4y ago

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.

amingilani 4y ago

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

arminiusreturns 4y ago

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

cjlm 4y ago

For something a bit more user-friendly check out flowchart.fun [0] – I just interviewed the sole developer [1] [0]: https://flowchart.fun/ https://flowchart.fun/ [1]: https://sourcetarget.email/editions/43/ https://sourcetarget.email/editions/43/

asimjalis 4y ago
Interesting. Is there a way to run it from the command line?
- cjlm 4y ago
  Yep! https://www.npmjs.com/package/flowchart-fun https://www.npmjs.com/package/flowchart-fun

tehwebguy 4y ago

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.

floverfelt 4y ago

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 https://github.com/floverfelt/pom-visualizer-maven-plugin

acidburnNSA 4y ago

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 https://whatisnuclear.com/energy-flow.html [2] https://i.imgur.com/SJjRaGH.jpg https://i.imgur.com/SJjRaGH.jpg

kimi 4y ago

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

eternityforest 4y ago

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.