Hi all, I'm Dominic and I'm on the product team at Mermaid. I enjoyed reading a lot of your feedback!
It seems there's several good ideas and thoughts on the direction of the platform that we'd love to learn more about. If you have problems with the current product, improvement requests, or would like to chat then let's connect! Please email me at dominic@mermaidchart.com or book time on my calendar: (https://calendly.com/dominic-01w/mermaid-shapers-product-int...)
<rant>
Aside, I'm the author of KeenWrite (https://keenwrite.com/), a Markdown text editor that allows embedding diagrams using the triple-backtick syntax. Here's a GraphViz example:
``` diagram-graphviz
digraph {
rankdir="LR";
a -> b -> c;
}
```
KeenWrite parses the `diagram-` prefix then passes the word `graphviz` to Kroki (https://kroki.io/), which has an API for rendering a variety of ASCII diagrams, including Mermaid. Meaning, if Kroki adds a new diagram type, KeenWrite gets it for free (without modification).
In Markdown, formatting a source code snippet entails using the standard syntax for code blocks:
``` graphviz
digraph {
rankdir="LR"
a -> b -> c;
}
```
GitHub created a de facto standard for Mermaid diagrams that breaks the convention of having triple-backticks followed by a language identifier to show the source code for that language in a monospace font. This was an unfortunate decision.
</rant>
Seconding the question on browserless rendering in the other comment. Having to (unseccessfully for us so far; the text renders incorrectly) tweak selenium setups to do headless builds is madness and I would have thought this to be top prio as a base feature beyond PoC for anything aiming for wide adoption.
I spent some time playing around with this recently and loved it at first. I also realized ChatGPT is pretty good at generating Mermaid diagrams (didn't try your own AI features).
However after getting into it some I ran into some significant frustrations. After creating a medium-complexity diagram, I was excited to see the Whiteboard feature to drag things around / improve the layout manually. But it really started breaking, it just wouldn't let me organize/drag things where I wanted, and I couldn't get things to not overlap. I also wished more diagram types supported Whiteboard (I noticed some didn't).
Also I some confusion between the capabilities of mermaidchart.com and mermaid.live. Are these competitors? Variations of similar apps. I was confused. Also "Playground" vs "Live Editor" is confusing.
Overall glad this exists and hope it continues to improve.
I hear you on the whiteboard. It's still in its early days. Should be substantially improved in the coming months.
To clarify on mermaidchart.com and mermaid.live, we are the same team. Mermaid.live is our fully open source hosted editor. This was the original editor for our 10 year old open source project. The creator of Mermaid recently founded mermaidchart.com with the CEO of Gitlab's venture studio to expand the capabilities of Mermaid for more users and build an enterprise grade product. The company is open core and venture backed. The Mermaid project will remain forever open source and will continue to invest in growing it and the company for those that desire more advanced business features.
We really appreciate your feedback and support. Ping me if you'd like to chat with our product team about the features you're hoping for:) andrew@mermaidchart.com
Please forgive my posting on the broader topic of Mermaid... The Mermaid package has gotten much bigger recently. Compare mermaid.min.js across a sampling of major releases:
All the new features are really cool, and maybe this is "fine" when mermaid itself is the purpose of the website (like this submission), but it's a bigger burden when mermaid is a value-add for generic markdown documentation: every visitor has to download and execute 3+MB of js just to view simple diagrams, or worse even when there are no diagrams on that page at all.
Is there a plan to reduce the required bundle size for viewers and users that only use a small subset of mermaid's wide feature set?
> it just wouldn't let me organize/drag things where I wanted, and I couldn't get things to not overlap
I suspect this might be a fundamental issue with mermaid. I've always had issues getting it to lay things out in any other way than how it "wants" me to, with giant gaps between things
This is definitely a gap in current Mermaid functionality. This is a gap we're aiming to close in 2025. Significant Whiteboard improvements and expanded diagram support is on the way! If you have a specific use case or diagram type you'd like us to keep in mind then let me know! dominic@mermaidchart.com
I only use diagramming tools with automatic layout algos to generate visualizations programmatically to debug things. For documentation purpose, I largely prefer to draw them by hand using OmniGraffle, because making graphs look nice using tools like graphviz is very complex and you find yourself abusing features to hack your vision into reality
What's dearly needed in my opinion is a graph layout algo based on a machine learning model (so that it can take into account readability and aesthetics). Unfortunately what I found so far is mostly concerned with displaying large graphs, which is kind of another domain altogether.
I hope Mermaid is collecting every single edition point that happens on their UI, that would make for a nice dataset I guess.
(I don't like to self promo on competitor posts, but since Mermaid doesn't compete in making its own layout engine I felt sharing this under this thread is relevant to HN. If anyone from Mermaid finds it in poor taste just let me know and I'll delete)
I tried TALA and am surprised to learn it embeds a machine learning model. I settled on ELK (very complex and time consuming to get right), before getting interested in constraint based graph layout (mostly for aligning nodes). Symmetry is nice to have too.
In fact what I'm trying to do is generating beautiful flow graph illustrations like this (non-sensical, just to give you a vibe):
This is really impressive! Excalidraw does some great work. Did you try Mermaid's integration with Obsidian? What was lacking and what ultimately hooked you on Excalidraw?
I do use mermaid quite a bit in markdown because it's documentation/code that can be updated, the idea tends to start in my notes as excalidraw, and eventually become a mermaid graph. I wouldn't say it's lacking anything. I have not tried it so I can't a valid opinion, but I am happy to give it a try and give some feedback. I do waste time converting. I see a couple of tools, do you recommend one in particular?
The only reason anyone uses mermaid is because it's low friction and most editors support it out of the box or through plugins.
But its layouting engine sucks and everything requires hacks and workarounds and configuration tweaks to display properly. Only the most trivial graphs render nicely on the first try.
All I really want to do is define how to actually lay out the blocks using a DSL so that they don't look like absolute shit. I hate drag and drop UIs and I hate mermaid. There's no decent code-first diagram building tool out there, let alone one that I can embed into my notes as easily as mermaid.
Hi! I'm Dominic from the Mermaid product team. You raise some good points here. We released the whiteboard to help users get an exact layout they'd like, but it's in its early stages and is undergoing a lot of improvements.
I understand that automatic layout algos is one of the big draws of Mermaid since it creates a lot of speed, but our current layouts can get a little convoluted. I like your idea on creating a machine learning model, but I'm curious what your biggest pain points are or if you have any basic requirements for a readable and aesthetic diagram. Is it made with hard corners on edges? Rounded?
Would love to hear any thoughts you might have on this! You can email me at dominic@mermaidchart.com if you'd be willing to share. Thanks for your comment!
I have been using the beta and would certainly appreciate a few more layouts. You can have a look at yEd for inspiration. Otherwise, it looks very promising!
I understand that it is different philosophy but I really would like to see the day when I can use Mermaid inside latex. Or at least get some robust mermaid to tikz converter. That would make my life much easy when preparing slides. I understand that exporting to PNG/JPG can work but usually you lose a lot of customization and you only know can make be bigger or smaller to fit the page.
I was exploring this yesterday and actually came acorss the new GUI that is being introduced in this submission. I ended up exporting to PNG and suffer with fitting it inside beamer page layout.
Thanks @maho! We're hoping to keep the improvements flowing. I'm non-technical but from my perspective I thought Mermaid sequence diagram functionality really shines! Would love to fill the gap in my knowledge. What is better about https://sequencediagram.org/ than Mermaid sequence diagrams?
I've used this in the past for collaborative diagramming sessions and love its ease and simplicity, but the point of Mermaid is its portability - ie. can be embedded in Markdown docs and viewed in various editors/platforms.
Hi! I'm Akshatha from the Product team at Mermaid Chart :)
While Draw.io's integration with Mermaid and the availability of plug-ins for VSCode and other IDEs are great, they primarily support programmatic editing of diagrams. What sets Mermaid Chart apart is its bi-directional editing capability. You can edit the code to update the diagram and make changes directly to the diagram, which will automatically reflect in the code.
Currently, this two-way editing functionality is available for class diagrams and flowcharts, but we're excited to expand it to other popular diagram types in the future. Stay tuned!
Hi all, I'm Dominic and I'm on the product team at Mermaid. I enjoyed reading a lot of your feedback!
It seems there's several good ideas and thoughts on the direction of the platform that we'd love to learn more about. If you have problems with the current product, improvement requests, or would like to chat then let's connect! Please email me at dominic@mermaidchart.com or book time on my calendar: (https://calendly.com/dominic-01w/mermaid-shapers-product-int...)
Thanks for taking a look at our latest release!
Any idea when Mermaid diagrams will render outside of web browsers?
https://github.com/mermaid-js/mermaid/issues/2485
<rant> Aside, I'm the author of KeenWrite (https://keenwrite.com/), a Markdown text editor that allows embedding diagrams using the triple-backtick syntax. Here's a GraphViz example:
KeenWrite parses the `diagram-` prefix then passes the word `graphviz` to Kroki (https://kroki.io/), which has an API for rendering a variety of ASCII diagrams, including Mermaid. Meaning, if Kroki adds a new diagram type, KeenWrite gets it for free (without modification).In Markdown, formatting a source code snippet entails using the standard syntax for code blocks:
GitHub created a de facto standard for Mermaid diagrams that breaks the convention of having triple-backticks followed by a language identifier to show the source code for that language in a monospace font. This was an unfortunate decision. </rant>Hello Dominic.
Seconding the question on browserless rendering in the other comment. Having to (unseccessfully for us so far; the text renders incorrectly) tweak selenium setups to do headless builds is madness and I would have thought this to be top prio as a base feature beyond PoC for anything aiming for wide adoption.
I spent some time playing around with this recently and loved it at first. I also realized ChatGPT is pretty good at generating Mermaid diagrams (didn't try your own AI features).
However after getting into it some I ran into some significant frustrations. After creating a medium-complexity diagram, I was excited to see the Whiteboard feature to drag things around / improve the layout manually. But it really started breaking, it just wouldn't let me organize/drag things where I wanted, and I couldn't get things to not overlap. I also wished more diagram types supported Whiteboard (I noticed some didn't).
Also I some confusion between the capabilities of mermaidchart.com and mermaid.live. Are these competitors? Variations of similar apps. I was confused. Also "Playground" vs "Live Editor" is confusing.
Overall glad this exists and hope it continues to improve.
Hi there, Mermaid CEO here:)
I hear you on the whiteboard. It's still in its early days. Should be substantially improved in the coming months.
To clarify on mermaidchart.com and mermaid.live, we are the same team. Mermaid.live is our fully open source hosted editor. This was the original editor for our 10 year old open source project. The creator of Mermaid recently founded mermaidchart.com with the CEO of Gitlab's venture studio to expand the capabilities of Mermaid for more users and build an enterprise grade product. The company is open core and venture backed. The Mermaid project will remain forever open source and will continue to invest in growing it and the company for those that desire more advanced business features.
We really appreciate your feedback and support. Ping me if you'd like to chat with our product team about the features you're hoping for:) andrew@mermaidchart.com
Please forgive my posting on the broader topic of Mermaid... The Mermaid package has gotten much bigger recently. Compare mermaid.min.js across a sampling of major releases:
All the new features are really cool, and maybe this is "fine" when mermaid itself is the purpose of the website (like this submission), but it's a bigger burden when mermaid is a value-add for generic markdown documentation: every visitor has to download and execute 3+MB of js just to view simple diagrams, or worse even when there are no diagrams on that page at all.Is there a plan to reduce the required bundle size for viewers and users that only use a small subset of mermaid's wide feature set?
Props for somehow convincing all the foundation models to generate charts using your markup. It is guaranteed to survive a very long time now.
Good choice of a product name. Totally applicable. /s I know single-word, unrelated product labelling is the shit for quite some years now.
I had the exact same set of issues and questions.
> it just wouldn't let me organize/drag things where I wanted, and I couldn't get things to not overlap
I suspect this might be a fundamental issue with mermaid. I've always had issues getting it to lay things out in any other way than how it "wants" me to, with giant gaps between things
This is definitely a gap in current Mermaid functionality. This is a gap we're aiming to close in 2025. Significant Whiteboard improvements and expanded diagram support is on the way! If you have a specific use case or diagram type you'd like us to keep in mind then let me know! dominic@mermaidchart.com
Thanks for your comment:)
I only use diagramming tools with automatic layout algos to generate visualizations programmatically to debug things. For documentation purpose, I largely prefer to draw them by hand using OmniGraffle, because making graphs look nice using tools like graphviz is very complex and you find yourself abusing features to hack your vision into reality
What's dearly needed in my opinion is a graph layout algo based on a machine learning model (so that it can take into account readability and aesthetics). Unfortunately what I found so far is mostly concerned with displaying large graphs, which is kind of another domain altogether.
I hope Mermaid is collecting every single edition point that happens on their UI, that would make for a nice dataset I guess.
We make (and sell) one, you can play with it here: https://play.d2lang.com/?script=qlDQtVOo5AIEAAD__w%3D%3D&lay...
Bigger example: https://play.d2lang.com/?script=rJLfavMwDMXv_RR6gYbvo3ce7FWG...
(I don't like to self promo on competitor posts, but since Mermaid doesn't compete in making its own layout engine I felt sharing this under this thread is relevant to HN. If anyone from Mermaid finds it in poor taste just let me know and I'll delete)
I tried TALA and am surprised to learn it embeds a machine learning model. I settled on ELK (very complex and time consuming to get right), before getting interested in constraint based graph layout (mostly for aligning nodes). Symmetry is nice to have too.
In fact what I'm trying to do is generating beautiful flow graph illustrations like this (non-sensical, just to give you a vibe):
https://th.bing.com/th/id/OIG4.sqo88280g1BDb7r2aORg?pid=ImgG...
Tis hard. Graph layout (bites fist). Layout based image diffusion (tears). One day though.
Is it possible to visualize PlantUML? I tried to paste some but it wasn’t very easy on mobile.
Also, some interesting links I stumbled upon while exploring this space:
Graphviz-like generic graph-drawing library. More options, more control.
https://eclipse.dev/elk/
Experiments by the same team responsible for the development of ELK, at Kiel University
https://github.com/kieler/KLighD
Kieler project wiki
https://rtsys.informatik.uni-kiel.de/confluence/display/KIEL...
Constraint-based graph drawing libraries
https://www.adaptagrams.org/
JS implementation
https://ialab.it.monash.edu/webcola/
Some cool stuff:
HOLA: Human-like Orthogonal Network Layout
https://ialab.it.monash.edu/~dwyer/papers/hola2015.pdf
Confluent Graphs demos: makes edges more readable.
https://www.aviz.fr/~bbach/confluentgraphs/
Stress-Minimizing Orthogonal Layout of Data Flow Diagrams with Ports
https://arxiv.org/pdf/1408.4626.pdf
Improved Optimal and Approximate Power Graph Compression for Clearer Visualisation of Dense Graphs
https://arxiv.org/pdf/1311.6996v1.pdf
I settled on excalidraw via obsidian
https://github.com/zsviczian/obsidian-excalidraw-plugin
This is really impressive! Excalidraw does some great work. Did you try Mermaid's integration with Obsidian? What was lacking and what ultimately hooked you on Excalidraw?
I do use mermaid quite a bit in markdown because it's documentation/code that can be updated, the idea tends to start in my notes as excalidraw, and eventually become a mermaid graph. I wouldn't say it's lacking anything. I have not tried it so I can't a valid opinion, but I am happy to give it a try and give some feedback. I do waste time converting. I see a couple of tools, do you recommend one in particular?
The only reason anyone uses mermaid is because it's low friction and most editors support it out of the box or through plugins.
But its layouting engine sucks and everything requires hacks and workarounds and configuration tweaks to display properly. Only the most trivial graphs render nicely on the first try.
All I really want to do is define how to actually lay out the blocks using a DSL so that they don't look like absolute shit. I hate drag and drop UIs and I hate mermaid. There's no decent code-first diagram building tool out there, let alone one that I can embed into my notes as easily as mermaid.
Hi! I'm Dominic from the Mermaid product team. You raise some good points here. We released the whiteboard to help users get an exact layout they'd like, but it's in its early stages and is undergoing a lot of improvements.
I understand that automatic layout algos is one of the big draws of Mermaid since it creates a lot of speed, but our current layouts can get a little convoluted. I like your idea on creating a machine learning model, but I'm curious what your biggest pain points are or if you have any basic requirements for a readable and aesthetic diagram. Is it made with hard corners on edges? Rounded?
Would love to hear any thoughts you might have on this! You can email me at dominic@mermaidchart.com if you'd be willing to share. Thanks for your comment!
I have been using the beta and would certainly appreciate a few more layouts. You can have a look at yEd for inspiration. Otherwise, it looks very promising!
I understand that it is different philosophy but I really would like to see the day when I can use Mermaid inside latex. Or at least get some robust mermaid to tikz converter. That would make my life much easy when preparing slides. I understand that exporting to PNG/JPG can work but usually you lose a lot of customization and you only know can make be bigger or smaller to fit the page.
I was exploring this yesterday and actually came acorss the new GUI that is being introduced in this submission. I ended up exporting to PNG and suffer with fitting it inside beamer page layout.
Nice! I love how mermaid keeps getting better!
For sequence-diagrams, nothing beats https://sequencediagram.org/ (I am not connected with them in any way, just a happy user)
Thanks @maho! We're hoping to keep the improvements flowing. I'm non-technical but from my perspective I thought Mermaid sequence diagram functionality really shines! Would love to fill the gap in my knowledge. What is better about https://sequencediagram.org/ than Mermaid sequence diagrams?
I've used this in the past for collaborative diagramming sessions and love its ease and simplicity, but the point of Mermaid is its portability - ie. can be embedded in Markdown docs and viewed in various editors/platforms.
Agreed. I’ve tried other editors but so far I’ve always come back to sequencediagram.org — it just works, low fuss.
sequencediagram.org is using PlantUML I believe, so you can do these locally without their website.
With Draw.io embedding Mermaid diagrams and plug-ins available for VSCode and other IDEs, why is this so special?
Hi! I'm Akshatha from the Product team at Mermaid Chart :)
While Draw.io's integration with Mermaid and the availability of plug-ins for VSCode and other IDEs are great, they primarily support programmatic editing of diagrams. What sets Mermaid Chart apart is its bi-directional editing capability. You can edit the code to update the diagram and make changes directly to the diagram, which will automatically reflect in the code.
Currently, this two-way editing functionality is available for class diagrams and flowcharts, but we're excited to expand it to other popular diagram types in the future. Stay tuned!
Competition is good for innovation and choice is good for everyone. Does it need to be special?
Heads up: the "Theme Customization in Toolbar" image isn't rendered.
Thanks for sharing!
Thanks, I uploaded it!
That's pretty cool. Wish PlantUML community would have something like it.
Do Mermaid class diagrams support generics (parameterized types)?
Yes
> … though generics that include a comma are currently not supported. [1]
So yes-ish, only in the most basic way.
[1] https://mermaid.js.org/syntax/classDiagram.html
This is great and all, but this would better be served as a desktop app with lower overhead.
Is there a demo available without creating an account?
Yes! You can use this in the free mermaid playground: https://www.mermaidchart.com/play