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 think the main reason why diagrams are not used as often as they should to document code bases is that we developers have to face opposite yet complementary approaches: text based graph specifications (but then the layout's quality doesn't scale with graph size), or GUI based approaches that lead to way better results but are too costly to maintain.
The idea of using machine learning is just a kind of knee jerk reaction to this fact. Maybe we could just throw graphs at a graph neural network and have the model learn all the features we are interested in without listing them explicitly (let alone the rules to decide which to prioritize). It's more an art than a science, really.
Among those listed in these papers[1][2] those I am the the most interesting in, beyond the usual overlap minimization, edge crossing and edge length reduction are the following:
symmetry/alignment
hierarchical layouts (subgraphs within nodes)
Fine-grained control of flow direction (doesn't have to be the same in each subgraph)
Those are the features that have constrained the most my search for a diagram engine. Aesthetics (I mean readability) is paramount to using diagrams as documentation IMO. They are not just graphs, they are mental palaces.
A palace's layout must not change if you decide to build an extension. Stability isn't guaranteed with most graph layout algos: add a node and you might end up with a graph that doesn't look like the previous version. Nodes shifts, edges move around. Confusing. There has been research in this direction[3], namely "interactive graph layout". It forces us to move away from a stateless approach to graph generation (graph specification -> picture) and into a stateful paradigm where the previous state of the layout will be preserved to some extent in the new version. With the layout specified as a mixture of previous layout state + constraints I could picture a pipeline where an LLM watches the commit log of some git repo and updates diagrams via semantic reasoning automatically with a 90% success rate, while the remaining 10% is left to the developer to fix.
And there is also "UI-bility". A high degree of customization, being able to plug your own (react,vue,whatever) components into a graph can turn it into a monitoring tool. I wrote an (incomplete) debugger for a go-style channel framework that displays interactions as sequential diagrams, and, although neither D2 nor PlantUML offer this, I had to give up on using the former because it did not provide on-hover tool-tips, which was critical for my use case.
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?
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.
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
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 think there are two slightly different issues here!
1. SVGs generated by Mermaid use the SVG 2 features, but other than browsers, most libraries only support SVG 1.1 features, i.e. <https://github.com/mermaid-js/mermaid/issues/2102>, which is what the other comment mentioned.
2. Mermaid requires a browser layout engine to render the diagrams (your issue), i.e. <https://github.com/mermaid-js/mermaid/issues/3650>. This is something I also really want to fix (I maintain the [`mermaid-js/mermaid-cli`][1] project and we need to use Puppeteer/Headless Chrome to render mermaid diagrams, which isn't ideal.) However, I don't think this would be easy, since we'd need a browserless tool that supports a browser-like layout engine (although I'm hoping that [Servo][2] might eventually be able to support it).
And if you do want to do headless renders of Mermaid diagrams, I'd recommend using (or adapting, since the code is all MIT licensed and I'm not aware of one that uses Selenium):
I’d like to see better controls for keeping diagram components from colliding. I’m sure that’s a nontrivial ask, but I run into poorly placed components quite frequently, and I feel like that’d be a major selling point for Mermaid for me if you could solve it
I work on the Mermaid Chart product team and your comment here is extremely relevant to a big project I'm working on that will solve a lot of the problems you mentioned! Would you be willing to tell me more and give your thoughts on our plan for solutions?
If you're open to it, please send me an email at dominic@mermaidchart.com!
I'd be happy to exchange an Amazon gift card for your time too!
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!
reply