This looks nice. Personally I prefer draw.io desktop version for large complex diagrams, and use mermaid for smaller diagrams such as sequence diagrams.
Thanks for the input! I'm also looking at supporting Mermaid diagramming https://mermaid-js.github.io/ I'd love to hear if people have other good use cases for this model, e.g., of having a plain text file you edit in a text editor accompanied by a rendered web document view of the same file.
I had just learned about Mermaid and used it standalone once, when I realized it is also already built into Github Markdown [0], where you can include a diagram by just going ```mermaid <code>```, which is veeery handy. In mermaid.live can also get an SVG URL which works great to paste into many online drawing tools like Miro, Diagrams.net etc.
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.
In Mermaid, while I like it a lot, you lose control of layout positioning. Does the auto-layout position large diagrams (many shapes + connectors) appropriately?
The Excalidraw export format is JSON, so you might use that in source control just as well. Or include the format in PNG or SVG export (which draw.io supports also).
If you start getting into this kind of thing, you'll want to take a look at https://kroki.io which supports Mermaid along with lots of other diagramming formats.
I definitely have made decent use of Mermaid diagrams in GitHub. But Mermaid diagrams are hard to layout, and there is only one experimental layout that's good for automatically generated diagrams. It's nice, but it's not quite there. I have tended to bounce between Mermaid and Visio.
I'm generally not a fan of exporting and importing diagrams constantly. One thing that is nice is that Confluence can support plugins for diagrams, which is okay-ish.
I believe Mermaid supports a wider range of diagram types than Graphviz. Graphviz doesn't support sequence diagrams, for instance, unless I'm missing something.
Mermaid would not be my first choice of diagramming software (that would be plain old Graphviz with PlantUML for more full featured graphs), but I'm glad to see some diagramming support on GitHub natively. There's already quite a few tools that let you embed via hotlink or generated link your graph.
Thank you very much for your work! I learned about mermaid about a year ago, and have used it pretty extensively since, including as a visualization and control interface for a DAG execution framework.
Mermaid’s flow chart layout engine is quite nice, too. I’ve yet to encounter the kind of messes that graphviz comes up with regularly, even with complicated flow charts.
reply