16 ms·
Include diagrams in your Markdown files with Mermaid
- JoshMandel 5y agoThis brings one of my favorite features from https://hackmd.io https://hackmd.io (a site that I still love for early collaboration). I still love hackmd for its "gists on steroids", though I wish it had included git hosting.
- aseattledev1234 5y agoThis is great, I have used mermaid for years and glad to see GitHub adding support.
- victor106 5y agoFor those interested in this I highly recommend the book mentioned in the blog post "The Official Guide to Mermaid.js"
- jopsen 5y agoI like the idea of mermaid.js, but why does it have to be so ugly. I don't know why, but whenever I've had a look at mermaid.js, it always made me feel like the syntax and generated diagrams were ugly. Am I the only one who thinks this? Also what's up with all the useless diagram types?
- eurasiantiger 5y agoYes, it is ugly. The layout engine doesn’t do ”these elements are kinda the same thing so place them side by side”. No hierarchy model, no constraints, everything is always placed on one axis according to order and then pretty much shifted randomly to not collide. Spiderwebs everywhere. Also, ER diagrams are nigh unreadable due to the unusual relationship visual style used.
- lpghatguy 5y agoThis is a problem I've always had with Mermaid too. Custom theming is a no-go; it's easier to make attractive diagrams with GraphViz. I remember the docs for Mermaid.js talk about varying document trust levels, which is not something I want involved in a diagramming DSL.
- innolitics 5y agoI really like diagrams as text for simple diagrams where you don't care too much about the formatting. I think Figma is better if you really care about the formatting. I just discovered this the other day, but you can create mermaid diagrams in Notion by adding a codeblocks and selecting the "mermaid" language from the dropdown.
- medv 5y agoAnsi draw tool what can parse boxes and move them?
- magicbuzz 5y agoBeen doing this for ages with GitLab
- Khaine 5y agoMonodraw is my favourite tool for creating ascii art, that you can then embed in markdown documents. This is currently how I document my home servers
- goodpoint 5y agographviz is much better. It does not need javascript and can render images as jpg and svg.
- goodpoint 5y agoSuch a pity to have a hodgepodge of markdown plus custom extensions.
- dan-robertson 5y agoHonestly, Friday deploys are the best deploys. You’re extra motivated to get things out, fewer people will be around to complain if things are going wrong (at least if you mostly make money in the week) and you want to go home so you’re motivated to just do it efficiently instead of hesitating. There is a risk of rolling bugs on the weekend but there’s also a risk of having to spend your Mondays fixing twice as many (on average) bugs from bad rolls as well as other issues that may have been discovered on the weekend. The best trick for deploying on Fridays is to not write bugs, write software that is easy to roll back, and/or spend your weekend away from any kind of mobile signal.
- luxurytent 5y agoWhat we do at our co is run a Hugo plugin which, when an SVG is embedded in the document, provides an _Edit in https://app.diagrams.net/_ https://app.diagrams.net/_ link for that SVG. IMO, this was the missing piece for us when it came to keeping diagrams up to date.
- creakingstairs 5y agoThat is such a great idea. Thank you for sharing that.
- mukundesh 5y agoWould be great if Github added maths support in markdown.
- Arubis 5y agoNeat! Hadn’t used Mermaid before today, and it was easy enough to pick up to do a same-day turnaround for a client-facing PR with an embedded flow diagram to support a needed discussion. I’ll be interested to see if/how visual diffs work out for this.
- hericium 5y agoJavaScript requirement for Markdown? Page views boost through terminal-unreadable documentation? Yeah... no. I prefer ASCII drawing characters/boxes, similar to mentioned in this[1] and following comments. [1] https://news.ycombinator.com/item?id=30275327 https://news.ycombinator.com/item?id=30275327
- southerntofu 5y agoI agree with your sentiment, although personally i like the mermaid syntax (as someone who's bad at drawing ASCII art). Are you aware of native implementations of the mermaid syntax which i could use part of my site pipeline to build SVGs/PNGs instead of rendering client-side with javascript?
- nunez 5y agoYay! I can design systems without draw.io, OmniGraffle, Visio, or Lucidchart! Very excited about this.
- charlieyu1 5y agoLooks very single-use and way too verbose. There should be a replacement of SVG that is not XML based and easy to use
- haberman 5y agoThe rendered sample looks notably blurrier than the surrounding text. Is it rendering to SVG? If not, why not?
- amiga-workbench 5y agoI started using this when I saw the initial announcement that they were working on integration. I've got all of my diagrams ripped out of lucidapp and into project repos, but the issue I'm having is that IntelliJ is still shipping a year+ outdated version of mermaid, which makes ordering nodes impossible in some cases.
- moontear 5y agoShoutout for Hedgedoc a fork of CodiMD - Hedgedoc supports Mermaid already next to a lot of other markdown syntax: https://hedgedoc.org/ https://hedgedoc.org/
- pietroppeter 5y agoMore mermaid support in an Nim library you never heard of: https://pietroppeter.github.io/nblog/drafts/mermaid_diagram.html https://pietroppeter.github.io/nblog/drafts/mermaid_diagram....
- porker 5y agoAm I the only person who thinks Mermaid output is visually unappealing? We tried to use it for flowcharts in our documentation and its layout wasn't right. I'm assuming it uses a force directed layout system. We switched to creating diagrams in Excalidraw and everyone is happy.
- dotancohen 5y agoThe fine article includes this code: ```mermaid flowchart TD; A[Depoy to production] --> B{Is it Friday?}; B -- Yes --> C[Do not deploy!]; B -- No --> D[Run deploy.sh to deploy!]; C --> E[Enjoy your weekend!]; D --> E[Enjoy your weekend!]; ``` What happens if the two declarations of E conflict? E.g.: C --> E[Enjoy your weekend!]; D --> E[Have fun this weekend!];
- tremon 5y agoThe latter takes precedence, apparently. But the correct way to do this: C --> E; D --> E; E[Enjoy your weekend!];
- hooby 5y agoFantastic idea - some rough edges in actual implementation though. Still, since GitHub does render Mermaid, it might be useful to create a GitHub action that automatically generates an updated diagram.MD directly from the models on every commit.
- kkirsche 5y agoIs GitHub supporting the author of mermaid? They explicitly have asked for help managing the volume of requests on the mermaid website
- DerWOK 5y agoZettlr[1] (FOSS) has mermaid support[2] included. Zettlr is a markdown editor for personal knowledge management and/or distraction free (scientific) writing w/ PDF publishing. [1] https://github.com/Zettlr/Zettlr https://github.com/Zettlr/Zettlr [2] https://docs.zettlr.com/en/reference/markdown-basics/#zettlr-markdown-additions https://docs.zettlr.com/en/reference/markdown-basics/#zettlr...
- adrianomartins 5y agoThis is pretty cool, something that I'd actually use if there was a simple SaaS option for it.
- michaelsbradley 5y agoGitHub? https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/ https://github.blog/2022-02-14-include-diagrams-markdown-fil...
- adrianomartins 5y agoAmazing! This is awesome news. Infinity useful.
- dylanowen 5y agoLike https://mermaid.live/ https://mermaid.live/ ?
- 2wrist 5y agoCooool, this is used on github https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/ https://github.blog/2022-02-14-include-diagrams-markdown-fil... Also on Azure DevOps too https://docs.microsoft.com/en-us/azure/devops/project/wiki/wiki-markdown-guidance?view=azure-devops https://docs.microsoft.com/en-us/azure/devops/project/wiki/w... What a time to be alive! :-)
- Brian-Puccio 5y agoAnd GitLab since v10.3: https://about.gitlab.com/releases/2017/12/22/gitlab-10-3-released/#flow-charts-sequence-diagrams-and-gantt-diagrams-in-gitlab-flavored-markdown-gfm-with-mermaid https://about.gitlab.com/releases/2017/12/22/gitlab-10-3-rel...
- hobo_mark 5y agoI hope these companies are sponsoring the maintainer of the project, even though I could not find nothing of the sort in his sponsors tab on github.
- k3liutZu 5y agoWe had a good number of diagrams in our readme.md files which worked fine on GitLab. And then we moved providers and GitHub wouldn't render then anymore. Very happy that 1.5 years later they are again being rendered.
- JadeNB 5y agoThe title got truncated ("Create complex diagrams using Markdown-inspired" … syntax, I guess?).
- luispa 5y agoYes, the original title was "Mermaid: a Javascript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams."
- chrisseaton 5y agoI'm using this to include compiler graphs in pull requests when discussing compiler optimisations https://github.com/Shopify/seafoam/pull/56 https://github.com/Shopify/seafoam/pull/56.
- rgrieselhuber 5y agoNice looking framework but it doesn’t seem to support features that would be useful on very large visualizations, such as zoom and zoom windows.
- Veuxdo 5y agoFor larger, multiperspective visualizations with zoom, Ilograph may be what you are looking for: https://www.ilograph.com/ https://www.ilograph.com/
- major505 5y agoI used this for documentation in a project. Its kind work intensive to update and keep the diagrams, but the fact that you can't sync with the code in GitHub is a real plus.
- xpil 5y agoI was recently evaluating Mermaid for one of my projects but I could not get mermaid-cli to work (one of 3rdparty npm libraries was broken) and I needed a way of automating graph creation. Does anyone know if there is a decent tool similar to mermaid-cli allowing for command-line based generating PNG or SVG mermaid diagrams, but without having to install bazillion of NPM packages first?
- oneplane 5y agoPlantUML or perhaps a pre-packaged draw.io. (yes, it works offline)
- capitainenemo 5y agoIs there any mermaid specification syntax for directly embedding diagrams into a markdown file (like by flagging the start of the diagram with a special title like #### diagramtypename) ? I was poking around the examples and live editor, and it seemed impossible to do except with an image link, which is rather more cumbersome.
- iLoveOncall 5y agoSeems like PlantUML with downsides.
- mappu 5y agoGitea has had this feature for a while, it's really excellent.
- rektide 5y agonicely seen[1] on their roadmap a month ago. not github specific but i really enjoyed this quite long post/tutorial on realtime collaboration with mermaid (using notion)[2]. [1] https://github.com/github/roadmap/issues/372 https://github.com/github/roadmap/issues/372 https://news.ycombinator.com/item?id=29927962 https://news.ycombinator.com/item?id=29927962 (72 points, 14 comments, 31 days ago) [2] https://www.happyandeffective.com/blog/realtime-collaborative-diagramming-in-notion-with-mermaidjs https://www.happyandeffective.com/blog/realtime-collaborativ... https://news.ycombinator.com/item?id=30238208 https://news.ycombinator.com/item?id=30238208 (12 points, 2 comments, 7 days ago
- deleted 5y ago[deleted]
- deleted 5y ago[deleted]
- j0yb0y 5y agoThis can be done with Bitbucket but the existing marketplace plug-in has been broken since they added the connect/disconnect webhooks as mandatory. Of course, the plug-in is provided by bitbucket …so that’s fun. I wrote a trivial webstack to answer 200 to the webhook and then everything works. (Don’t know if I can publish it unfortunately.) (Condolences to those stuck on Bitbucket).
- tjk_ 5y agoMind if I ask if you're having this issue on Bitbucket Cloud (bitbucket.org) or Bitbucket Server (self-hosted)?
- thrower123 5y agoHuh, they must have taken the integration they've had for a couple years now on the Azure Devops wikis and shifted it over to the GitHub side.
- ktzar 5y agoI hope they support the full suite of mermaid diagrams, not just a small subset like they do in Azure DevOps. Which is quite frustrating. My team has to take pngs and keep the source code at the bottom of wiki pages.
- stakkur 5y agoThereby creating a hard dependency for your markdown files, obviating their portability.
- animal_spirits 5y agoThere's no hard dependency at all. The markdown will parse just fine without mermaid.js, it basically just takes a code block and runs it through the mermaid.js code if it matches the language
- djur 5y agoThere's also been other Markdown renderers that support this exact syntax for Mermaid blocks for ages. I have a site that's generated using mkdocs that uses Mermaid diagrams, and I was able to open up one of the files from that site in Github and view the diagrams.
- stakkur 5y agoI'm not talking about a dependency for the file to be readable. I'm talking about a dependency for the diagram to be useful. I'm not opposed to extending markdown, but most functionality like this seems to involve bolting on external dependencies to take advantage of it.
- animal_spirits 5y agoSo you want every markdown parser to support building diagrams as well? That seems much more difficult than offloading it to an open source library. Why waste effort that already has gone into building an easy to read diagraming language?
- akubera 5y agoI'm pretty sure stakkur means mermaidjs is a bad option for markdown, as its source form is not "useful" as a diagram, and that it's actually GitHub which is saying every "markdown parser (/renderer) should support building diagrams as well" since they're encouraging its use by supporting the syntax. The real criticism of the original comment is that markdown has never really been "portable"; yes there's now a hard dependency (for some definition of "hard") on mermaidjs for GitHub-flavored-markdown, but that actually brings it in line with other implementations. So has portability been obviated or just slightly changed?
- timwis 5y agoI’m super excited for this! One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md: ```js const foo = 1 + 1 ``` Rendered as: `2` ? Isn’t that kind of what we’re doing here with the mermaid source tag? That tag is for showing source code, no? Feels like there should be another tag for rendering it.
- asiachick 5y agoYes, it sucks. This is why we can't have nice things. Because a million different programmers always choose some random incompatible interpretation and then we're all stuck with it. Another similar example, all of VSCode's configuration files are called filename.json but they aren't actually json (any spec compliant json parser would barf on them). They could just have easily named them filename.jsonc (or whatever they actually are) but they didn't so we're stuck with all these .json files that json parsers won't actually parse and special hacks to validate them differently based on like if they're in a .vscode folder or if their name is some specific filename. Unfortunately there's no way to wrangle millions of programmers so we're stuck with whatever bad decisions become popular. IF that's not clear above, for example, trailing commas and comments are not allowed in JSON but they are in JSONC. You'd like your editor to highlight errors. Typically this is done by filename extension. .json = comments show as errors, .jsonc = comments OK. But VSCode named it's .jsonc files as .json so every editor that wants to be able to show if there are errors in your file now needs some random heuristic to decide how to interpret the file..... all because of a bad decision by 1 or 2 programmers that ended up being popular and now their too entrenched to fix it. The same thing is true here. ``` is supposed to mark a codeblock as in show the text as is, whitespace as is, line breaks as is. If you want to write a tutorial on how to use mermaid in markdown you'd want ``` to show the mermaid source. Use some other tag for rendering. But now where stuck with an exception and more will be added. And before you go say "there's no official spec", so what!? It's called being consistent and interpreting the contents of a ``` block is inconsistent.
- anchpop 5y agoIf I could have one wish, I'd replace file extensions with a hash of the spec and have someone maintain a lookup table from spec hash -> extension for rendering
- 0xbadcafebee 5y agoDo they support a markdown Table of Contents yet?
- infensus 5y agoNot as a syntax, but headings are parsed and there's a TOC dropdown to the left of the filename
- jonpalmisc 5y agoI think this is a good change. While I would have preferred to see support for Graphviz over Mermaid, I understand Mermaid was probably chosen for the sake of easier integration. Either way, it will be nice to be able to embed diagrams rather than constantly re-generate and re-commit images to the repo.
- WalterGR 5y agoHas Graphviz been re-implemented in JavaScript or compiled to WASM?
- jonpalmisc 5y agoThere are definitely some JS libraries for it that exist. I don’t know all the details but I often find myself Googling “graphviz online” and clicking the first link to quickly mock up diagrams. So in short, I’ve used it on the web before.
- lelandbatey 5y agoOther services, such as Gitlab[0], allow you to embed Graphviz & PlantUML into a README just like (and alongside) Mermaid, but the images are rendered server-side. [0] - https://docs.gitlab.com/ee/administration/integration/plantuml.html https://docs.gitlab.com/ee/administration/integration/plantu...
- donatj 5y agoIt's a simple well documented language. Righting a fully functional JS Graphviz parser from scratch would take a couple days at most.
- deleted 5y ago[deleted]
- WalterGR 5y agoThe parser is only the beginning. Table stakes. For example: GraphViz has 8 layout engines. Which of those need to be implemented in JS?
- floodle 5y agoI'm curious why they went for mermaid rather then GraphViz. Can anybody comment?
- limmeau 5y agoMermaid has explicit support for diagrams that look UML-ish (never mind the filled triangle arrowheads for inheritance): class, state and sequence diagrams. Graphviz doesn't do that easily.
- lelandbatey 5y agoPlantUML[0], which is built on top of Graphviz, does have support for UML and other services such as Gitlab do support direct embedding of PlantUML (which also means you can embed Graphviz, since PlantUML is an extension of Graphviz). [0] - https://plantuml.com/object-diagram https://plantuml.com/object-diagram
- eminence32 5y agoGitlab supports mermaid too. It's always nice when there's feature parity between the two, as it makes it easier to jump between them.
- wjdp 5y agoBeen using it in Gitlab for a while, was rather surprised Github didn't support it when I pushed a repo there. There was an outstanding feature request on their forum for quite some while so didn't hold my breath for this to be added but glad it has.
- this_steve_j 5y agoAzure Devops wikis have excellent (although not full support) for mermaid diagrams. One power user feature I like is the ability to add a hyperlink to graph nodes like so: click NodeName “URL”
- kaycebasques 5y agosequencediagram.org is a pleasant (and free) tool for generating standalone diagrams like this outside of GitHub. I discovered it while helping Corrily with their docs, e.g. the diagram at the top of this page: https://docs.corrily.com/docs/price-optimization-overview https://docs.corrily.com/docs/price-optimization-overview
- roboyoshi 5y agoyou might also enjoy swimlanes.io
- lelandbatey 5y agoSomething to know is that sequencediagram.org seems to be just a website skin around PlantUML Sequence Diagrams[0]. PlantUML is open source and is ultimately built on top of Graphviz as well. Another nice thing is that PlantUML is supported (alongside Mermaid) in GitLab, and has been supported for at least two years. You can embed PlantUML diagrams into your README without committing any images to the repo or linking to external images, just like Mermaid.[1] [0] - https://plantuml.com/sequence-diagram https://plantuml.com/sequence-diagram [1] - https://docs.gitlab.com/ee/administration/integration/plantuml.html https://docs.gitlab.com/ee/administration/integration/plantu...
- HNSucksAss 5y ago
- ghostoftiber 5y agoI want a lucidchart or drawio style support for mermaid. There's plugins to let them render mermaid.md files but I haven't seen anything which just lets me draw arrows between shapes and label things. Someone please make this happen, I will be forever grateful.
- zellyn 5y agoLike pikchr.org? I love it. Now I have to see if I can get pikchr support added to Mermaid, and we'll be off to the races!
- sidharthv 5y agoWould you be willing to file a feature request in https://github.com/mermaid-js/mermaid-live-editor/issues https://github.com/mermaid-js/mermaid-live-editor/issues ? Disclosure: I'm a maintainer for the project and the feature will be a bit tricky, but should be doable. One issue is that unlike drawio, mermaid doesn't support custom placement of nodes. We could have different style arrow popups, which could render corresponding connections in default locations. I also feel that this would be a very nice feature to have. If anyone is interested in implementing, please let us know, and we can discuss ideas.
- ak217 5y agoMermaid is fantastic. Aside from mermaid, I've recently been introduced to nomnoml (https://nomnoml.com/ https://nomnoml.com/) and it is fantastic as well. My wish is for Mermaid and nomnoml to become universally supported among Markdown web renderers (I'm looking first and foremost at Github of course).
- Ciph 5y agoI love mermaid, but I'm also very annoyed by the variety of how its implemented in different markdown editors. One thing that I find quite annoying is the lack of fontawesome support - afaik only the live mermaid editor and hack.md supports it out of the box. Other editors require a lot of .conf file editing. Thanks for the tip of nomnoml, didn't know about it.
- KaoruAoiShiho 5y agoI'm using mermaid to render this route map for interactive fiction: https://fiction.live/tsukihime/Satsuki-Yumizuka-Route/4B9obcHdi7CLnaid9/routes https://fiction.live/tsukihime/Satsuki-Yumizuka-Route/4B9obc... How does nomnoml compare? The results are with mermaid are not ideal for me. Edit: That one above is actually relatively decent. The results with mermaid can get a lot worse, actually to the point of uselessness. Terrible examples below https://fiction.live/stories/The-Hypno-Games/eSSzPJ6qiqAC7466i/routes https://fiction.live/stories/The-Hypno-Games/eSSzPJ6qiqAC746... https://fiction.live/stories/The-Gynarchy/czyGfAtJpRgtzGFmW/routes https://fiction.live/stories/The-Gynarchy/czyGfAtJpRgtzGFmW/...
- sundarurfriend 5y agoNot sure why, but none of these render anything for me. It gives the progress message, then I get a plain square with no content in it. I've tried Firefox with and without uBlock enabled, and Brave with "Shields" up and down. edit: Oh, I'm on Linux btw.
- thuringia 5y agoI don’t know about nomnoml but dot/graphviz works very well for this type of chart. Definitely another idea to try out. PS: thanks for investing so much work into Tsukihime!
- avgcorrection 5y agoI think so-called ASCII-art is more in the spirit of Markdown. The nice thing about the original Markdown (modulo bugs) is that things are written the way one would write plaintext documents which are supposed to be easily read in a text editor. So you don’t write bullet lists like this: - Bullet 1 - Bullet 2 - Bullet 3 And hope that some post-processing will add linebreaks for you. You write it like this: - Bullet 1 - Bullet 2 - Bullet 3 Similarily there have been many tools that let you add so-called ASCII-art diagrams to Markdown documents. The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal. So if I were to judge the syntax itself (since that is what matters most to the original spirit of Markdown.pl) I would say that it seems pretty decent. Not as “declarative” (!) as ASCII-art, but most probably much easier to edit.
- jasonlotito 5y agoASCII-art is generally difficult to write as denoted by the numerous tools that have been created to generate ASCII-art for markdown. ASCII-art is also much more difficult to edit after the fact. The spirit of Markdown is succinctly described on DF's Markdown project website. "Markdown allows you to write using an easy-to-read, easy-to-write plain text format." Mermaid makes it easy-to-read and easy-to-write. ASCII is easy-to-read, but hardly easy-to-write. While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art. Finally, Markdown itself was designed that while the text is easy to read, Markdown itself is a conversion tool. It literally takes the text and changes it into something that is more readable. This can be seen with how Markdown handles tables. It's literally HTML table tags rather than ASCII designed tables. This is very much in the spirit of Markdown, and things like this have already been done in the original implementation.
- avgcorrection 5y ago> The spirit of Markdown is succinctly described on DF's Markdown project website. > "Markdown allows you to write using an easy-to-read, easy-to-write plain text format." The third/fourth person to quote the original article while failing to acknowledge this paragraph from the same article: > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. Your quote brings up two things that might be in conflict sometimes: 1. Being easy to write 2. Being easy to read Given that the “overriding design goal” (my emphasis) is to be as “readable as possible”, it immediately follows that (2) takes precedence over (1). Which is why you assertion here: > While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art. Misses the point—the original spirit is to be easy to read, and that does (by implication) take precedence over being easy to write.
- p20z 5y agohas anyone had success using mermaid diagrams for real-time collaboration? Seems you should be able to use this to draw pictures while chatting with someone, akin to a white-boarding experience.
- kilovoltaire 5y agoThis is interesting, but I personally really like that markdown is almost as legible as plain text as when rendered, which things like this sort of break. So I think I'd prefer ASCII art diagrams for this sort of thing. (In fact there was recently an ASCII diagram drawing tool on the HN front page, https://asciiflow.com/ https://asciiflow.com/ )
- prog5 5y ago+1 to asciiflow. huge fan. better than mermaid, imo... diagram wont need special rendering and works in vim and all text editors.
- bumblebeast 5y agoIt would be nice to have this tool: http://ditaa.sourceforge.net/ http://ditaa.sourceforge.net/ So ASCII drawings could be rendered into pretty ones.
- MrTortoise 5y agoI love how people keep discovering mermaid because i remember when i did many many years ago and it still brings me happiness today.
- mongol 5y agoMermaid looks similar to PlantUML. Anyone that gave used both and can compare?
- Ciph 5y agoThey are quite similar, PlantUML has support for more types of diagrams than mermaid (such as network diagram), but IMO PlantUML is "messier" to write, I find Mermaid more elegant in writing diagrams.
- majkinetor 5y agoPlantUML offered more decade ago. Marmaid is a toy compared to it. However, since its so powerful, its hard to write. Actually, any given diagram is not that hard, but to keep all those syntax rules in head is IMO almost impossible.
- pizza234 5y agoIn the past I used to use Mermaid for simple (but not trivial) flow charts and class diagrams. I've found some minor rough edges, but in particular, a couple of missing features, one of which I needed (edges going from attribute to attribute in class diagrams). PlantUML didn't have any of those limitations, so I switched, and never looked back. For simple-but-not-trivial diagrams, I didn't find any substantial difference in terms of syntax (complexity). I don't have experience on complex diagrams, though.
- sandreas 5y agoI like svgbob[1] and textik[2]. Far from perfect, but pretty good already. [1]: https://ivanceras.github.io/svgbob-editor/ https://ivanceras.github.io/svgbob-editor/ [2]: https://textik.com https://textik.com
- blackdogie 5y agoThis is a nice addition. I would love to see it working in the Github Wiki too.
- no-dr-onboard 5y agoProtip to anyone using Mermaid.js Don't. It's a sea shanty of XSS vulns. https://snyk.io/vuln/npm%3Amermaid https://snyk.io/vuln/npm%3Amermaid
- deleted 5y ago[deleted]
- billconan 5y agoI don't quite understand. Does XSS mean it runs user submitted js code? I thought it would have a parser that parses the submitted code to generate its own graph representation. there shouldn't be a chance for running js, no?
- deleted 5y ago[deleted]
- DiabloD3 5y agoThis seems to be incorrect, the current version has no CVEs according to that tracker.
- deleted 5y ago[deleted]
- kuroguro 5y agoI think the parent comment is just saying that multiple vulns have been found recently. There's a good chance there's more.
- dima55 5y agoorg-mode and org-babel already do this
- deleted 5y ago[deleted]
- w4rh4wk5 5y agoSemi-related question: does mermaid-cli still bring along chromium to 'render' images?
- donio 5y agoI just tried to install it and yes, it looks like mmdc still requires puppeteer and chromium. Which seems a bit ridiculous for a CLI tool.
- schemescape 5y agoYes, it uses browser APIs (e.g. SVGGraphicsElement.getBBox()) to measure text, compute transformations, etc. I had hoped to use Mermaid in a static site generator to create SVG diagrams at build time (to avoid requiring JavaScript), and this dependency was irritating enough that I abandoned Mermaid entirely and instead compiled Graphviz to WebAssembly (and honestly I prefer Graphviz's syntax, although it doesn't support nearly as many diagram types as Mermaid).
- w4rh4wk5 5y agoYeah, I was wanted to use the Git graph feature to create some nice diagrams. I expected the cli to work just like graphviz. Yet I was greeted by a stacktrace from Chromium since it did not work in WSL. The whole idea of depending on a full blown Chromium for your cli tool just to convert that mermaid description into an SVG or PNG seems bad to me. It was my personal turning point where I stopped using JavaScript based tools in my toolbox.
- a-dub 5y agothis looks excellent! last time i needed something like this it was fairly time consuming to do it in tikz, something quick in markdown is an awesome idea!
- msdrigg 5y agoCool, now do latex
- martinwoodward 5y agoTalking about it - https://talk.commonmark.org/t/math-rendering-re-visited/4086 https://talk.commonmark.org/t/math-rendering-re-visited/4086
- boomskats 5y agoWell this only took a few years! So happy to finally see it in. They should really unlock this issue[0] and let people know. [0] https://github.com/github/markup/issues/533 https://github.com/github/markup/issues/533
- riffic 5y agoif you use Obsidian, Mermaid is supported natively.
- chrisweekly 5y agoYeah, IMHO Obsidian is in a class of its own for markdown-based PKM / TFT / devnotes. And the Excalidraw plugin for Obsidian is absolutely phenomenal.
- theshrike79 5y agoObsidian's "a vault is just a directory structure with markdown files" is the biggest reason I use it.
- riffic 5y agoI've seen Excalidraw mentioned quite a few times, you've just given me a nudge to go check it out. Thanks for the plug.
- plett 5y agoIt works in Joplin too
- berkes 5y agoJoplin, the Open source note-taking app¹, has Mermaid built-in. I use those a lot when keeping my notes on arcitectures, design patterns and software design. I prefer this, vastly, over Google Docs + draw.io. The only thing I dislike about Mermaid-in-Joplin is that the live-pre-render of the actual chart fails and shows an error whenever there is an error in the source of the diagram. Which makes sense. But is annoying because *when you are typing out the syntax, there always is an error untill you finish the class, object, some bracket or relation. ¹https://joplinapp.org/ https://joplinapp.org/ EDIT: I'm not affiliated to joplin in any way. Just love it.
- milofeynman 5y agoI use Joplin at home and want to use it for taking notes at work. I love it.
- wscott 5y agohttps://obsidian.md/ https://obsidian.md/ can also render Mermaid diagrams
- Ciph 5y agoAnother annoyance is how the sync between the editor and preview pane "jumps" uncontrollably when using mermaid. I do however love it too and comitted to use it over other note-taking software.
- laurent123456 5y agoThis is a known issue which hopefully should be fixed soon: https://github.com/laurent22/joplin/issues/6074 https://github.com/laurent22/joplin/issues/6074
- deleted 5y ago[deleted]
- Someone 5y agoI like markdown, and can see the lure of additions such as this one, but I also sometimes wonder whether we gained much compared to troff and its companion programs (pic, eqn, tbl, chem, etc. See https://www.troff.org/prog.html https://www.troff.org/prog.html). If we added Unicode support and html and pdf output to those, I think the main thing we would miss is readability of the raw text. That doesn’t look like much progress in half a century.
- tannhaeuser 5y ago> That doesn’t look like much progress in half a century. Considering the author of groff became the SGML expert, with SGML supporting custom syntax parsing ranging from troff-like line commands all the way to markdown or Wikimedia syntax or subsets thereof precisely for unifying ad-hoc syntax, and SGML the basis for the HTML vocabulary from which these want to run away, I'd rather say tech is re-invented in generational circles. Or devs simply like to grow mini languages ;)
- tombert 5y agoI'm surprised I've never heard of this...there appears to be a pandoc filter readily available for this. This will be useful...
- mafro 5y agoI use Monodraw on macOS and then embed the ASCII art into the Markdown in my README. For example, https://github.com/mafrosis/step-ca-on-rpi#sso-for-ssh https://github.com/mafrosis/step-ca-on-rpi#sso-for-ssh I'd usually commit the source .monodraw files to the repo, but for some reason I didn't in that example repo :/
- kderbyma 5y agomermaid is great. I used a mermaid plugin for my own markdown support - formatting took a bit of a hit so maybe this will prompt better native support.
- thangalin 5y agoRe: https://github.com/github/markup/issues/533 https://github.com/github/markup/issues/533 I’m the main author of KeenWrite (see screenshots[1]), a type of desktop Markdown editor that supports diagrams. It’s encouraging to see that Mermaid diagrams are being supported in GitHub. There are a few drawbacks on the syntax and implications of using MermaidJS. First, only browser-based SVG renderers can correctly parse Mermaid diagrams. I’ve tested Apache Batik, svgSalamander, resvg, rsvg-convert, svglib, CairoSVG, ConTeXt, and QtSVG. See issue 2485[2]. This implies that typesetting Mermaid diagrams is not currently possible. In effect, by including Mermaid diagrams, many documents will be restricted to web-based output, excluding the possibility of producing PDF documents based on GitHub markdown documents (for the foreseeable future). Second, there are numerous text-to-diagram facilities available beyond Mermaid. The server at https://kroki.io/ https://kroki.io/ supports Mermaid, PlantUML, Graphviz, byte fields, and many more. While including MermaidJS is a great step forward, supporting Kroki diagrams would allow a much greater variety. (Most diagrams produced in MermaidJS can also be crafted in Graphviz, albeit with less terse syntax.) Third, see the CommonMark discussion thread[3] referring to a syntax for diagrams. It’s unfortunate that a standard “namespace” concept was not proposed. Fourth, KeenWrite integrates Kroki. To do so, it uses a variation on the syntax: ``` diagram-mermaid ``` ``` diagram-graphviz ``` ``` diagram-plantuml ``` The diagram- prefix tells KeenWrite that the content is a diagram. The prefix is necessary to allow using any diagram supported by a Kroki server without having to hard-code the supported diagram type within KeenWrite. Otherwise, there is no simple way to allow a user to mark up a code block with their own text style that may coincide with an existing diagram type name. Fifth, if ever someone wants to invent a programming language named Mermaid (see MeLa), then it precludes the possibility of using the following de facto syntax highlighting: ``` mermaid ``` My feature request is to add support for Kroki and the diagram- prefix syntax. That is: ``` diagram-mermaid ``` And deprecate the following syntax: ``` mermaid ``` And, later, introduce the language- prefix for defining code blocks that highlight syntax. That is, further deprecate: ``` java ``` With the following: ``` language-java ``` That would provide a “namespace” of sorts to avoid naming conflicts in the future. [1]: https://github.com/DaveJarvis/keenwrite/blob/master/docs/screenshots.md https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr... [2]: https://github.com/mermaid-js/mermaid/issues/2485 https://github.com/mermaid-js/mermaid/issues/2485 [3]: https://talk.commonmark.org/t/mermaid-generation-of-diagrams-and-flowcharts-from-text-in-a-similar-manner-as-markdown/1882 https://talk.commonmark.org/t/mermaid-generation-of-diagrams...
- donatj 5y agoWith Mermaid, the usage seems very locked down to a handful of use cases. I want to be able to point a method of a classDiagram at a decision chart with arrows then to the row of a database table. This is the sort of thing I reach to either Graphiviz or for Omnigraffle currently, and this doesn't seem to solve. With Mermaid each type of diagram is distinct and locked down to specific intended uses.
- emj 5y agoIETF RFCs has some nice diagrams in ASCII https://datatracker.ietf.org/doc/html/rfc5905 https://datatracker.ietf.org/doc/html/rfc5905 Also The Arte of ASCII RFC8140 https://datatracker.ietf.org/doc/html/rfc8140 https://datatracker.ietf.org/doc/html/rfc8140
- smasher164 5y agoI like this approach of using the tag associated with a code block to determine how to render the output. It's the same approach I take in my markdown-derived markup language: https://github.com/smasher164/mexdown https://github.com/smasher164/mexdown. The top example there takes a GraphViz description and passes it into the dot command, placing the resultant SVG into the HTML output.
- chrisweekly 5y agoIf you start getting into this kind of thing, you'll want to take a look at https://kroki.io https://kroki.io which supports Mermaid along with lots of other diagramming formats.
- urashidmalik 5y agoThat is pretty complicated Just use 1. Visual code draw.io extenstion 2. Save diagram as FILENAME.drawio.svg 3. Link file in markdown
- cybarDOTlive 5y agochad
- petepete 5y agoThen you change an arrow in your diagram and your diff is nonsense. I'd have preferred PlantUML but Mermaid is a great start.
- zmmmmm 5y agoBeen using in this way with Gitlab along with PlantUML for years. Slightly prefer PlantUML, feel like its a little bit more similar to native markdown due to the way it employs natural language. Would be nice if Github looked at that option too.
- spacexsucks 5y agoBeen using plantuml for ever in gitlab markdown. But lets reinvent the world in Js.. NIH is strong
- citizenkeen 5y agoJust so we're clear, if I deploy to production on a Monday, I get to start enjoying my weekend?
- perth 5y agoI love Mermaid! I used to use that bitch all the time in college to make beautiful flowcharts and my friends would always ask me how I made them so nice looking. Another awesome thing about Mermaid is since it’s grounded in the HTML/CSS/JS web stack you can easily modify certain things in diagrams to do any custom tricks you need for your specific diagram. Aka Mermaid is hackable and I love software that is designed to give you that freedom.
- MonaroVXR 5y agoCan you show more?