I have found these fun to work with, and ChatGPT has been pretty useful to play with: using it take code and create a sequence diagram, take a sequence diagram and create code (in one language, then another). It's pretty interesting and code generated can be tested so this feels like a good workbench to have for development. I am looking forward to trying Copilot Chat which should have these same capabilities (I hope).
I'm looking at its GitHub repo and it lists puppeteer as a dependency. There's even a puppeteer-config.json in there, so I assume it still requires having Node and running a headless browser in the background.
Having to use npm did put me off initially (as I had never used it, or JS, before), but it was quite painless, and now I have pretty sequence diagrams inline my org-mode docs. Its is about a billion time better than using the confluence builtin WYSIWYG graph builder.
Check out seqdiag, part of blockdiag [1]. It's python-based and uses graphviz (AFAIK) to generate sequence diagrams in SVG. I've used it several times and found it very good.
I'm one of the maintainers of the mermaid-cli project, and unfortunately, no.
Mermaid needs a browser's layout engine to run properly [1], but I haven't yet seen a library that will help us without puppeteer.
And yep, NPM (or another Node.JS package manager) is still needed for installation. I was working on trying to bundle all of mermaid-cli's dependencies (aka Node.JS, puppeteer) into one massive single-file exe last weekend, but it's seems we're blocked by missing features in other packages [2].
If anyone has any ideas on how to implement these things easily, feel free to help-out :) I'm also not a big fan of puppeteer, so I'd love to see a way to go without it.
My guess would be that text layout and measuring is something that's very easy to offload to the browser, yet, if you want to do this without, you're pulling in a whole lot of other dependencies (text rendering is quite complex) that you maybe cannot reasonably call from JS.
That's pretty much it. All modern browsers come with CSS layout functions [1], even Internet Explorer did! Pretty much every other Web API can be implemented in Node.JS using something like JSDom [2], but the CSS layout engine is the main missing feature. And the creator of JSDom estimated it would take 3-6 months of full-time work from a talented engineer to implement something like this [3], so this might take a while.
---
Just to give you an idea of how hard this would be, Mermaid let's people use custom fonts, with fallbacks, so diagrams can look quite different depending on what font people have installed.
The current default font is Tahoma [4], which is owned by Microsoft, so Linux desktops usually render the diagrams slightly differently than on Windows/MacOS desktops.
People can also have different default font size in their browser/OS settings, and that will affect things too.
Finally, you also have things like ClearType [5], where the text is rendered differently depending on the sub-pixel arrangement of your monitor!!
I think we could get a basic version that partially works by implementing only a subset of the layout functions and hard-coding one specific font in, but even that would still be a fair bit of work.
Currently I generate graph diagrams for papers and blog articles in emacs with graphviz, I wonder how mermaid.js compares in that workflow.
The default styles in mermaid look a little nicer than graphviz, which might be enough to motivate me to try it out. When/if I do, I'll probably try with this emacs package: https://github.com/abrochard/mermaid-mode.
Have you tried converting the dot file to svg and manipulating the svg file in the build process to improve its appearance? I'm not sure if it's worth the effort but perhaps it's a viable alternative.
I can highly recommend PlantUML as a simple language for creating sequence diagrams. It also supports other UML diagram types, which, despite what the article says, are also useful sometimes (so long as you don't worry about every last silly detail that's specified in the standard).
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml
That features is also a feature Mermaid/Markdown renderers have borrowed from existing uses of PlantUML. You've been able to embed PlantUML in a Markdown block in Gitlab (and have it rendered inline as an image) since before MermaidJS ever existed. Github's embedded MermaidJS feature is years late.
This is my go to diagramming tool. It takes a lot of little tricks to get things to turn out exactly how you want, but they're not required. It communicates information just fine. The tricks are only required if you care about aesthetics.
It does look nice, and covers most things, except for life lines. Is there a way to add life lines?
And why do so many tools choose to ignore life lines and provide incomplete sequence diagrams? Perhaps it gets really complicated to express in such a simple way as the examples do?
I would like if PlantUML would be implemented in some lighter language. JVM size and startup time is atrocious. You can easily notice latency caused by it even on modern hardware when rendering diagrams locally. In CI/CD it takes too much time to install JRE and run PlantUML. Probably, I can optimize it to some extent, but if it were implemented in another language, I wouldn't have to spend my time on it. Everything Java related is a monstrosity in size and consumed resources (CPU, RAM).
+1 for Plantuml. It has a great ecosystem, but there are certainly tradeoffs vs using mermaidjs, because of their different compilation models. Mermaidjs seems to look nicer out of the box as well, but usually that's not the point for a sequence diagram.
I'd use whichever works for your ecosystem and diagram lifecycle. The syntax is similar enough that I think the diagram creation constraints are often a bigger difference.
https://sequencediagram.org/ is the best sequence diagram tool like that. It does diagram-to-text to if you draw a line etc with mouse. Can right click and have context options too.
That looks nice but it's a shame that it uses its own proprietary language (not PlatUML or MermaidJS) and the code isn't even available. So if you use it then you have to cross your fingers that the website continues to be available otherwise your diagrams will suddenly become unmaintainable.
When rendered as an image, they don't differ; you'd have to inline the SVG DOM in your HTML to make a difference. And yes, then you can have screen readers reading the text, ARIA attributes to better describe certain parts, etc.
That being said, SVG is likely still a better option than PNG for its scalability alone. At least for this kind of content.
I have used Mermaid diagrams quite a bit lately because ChatGPT can generate them. It's been an easy way to get it to visualize things before I have access to the image generation stuff. It works really well, try it if you haven't!
I only wish the renderer could render "sketch" style like Excalidraw, I don't like the default appearance. Obviously a small detail, though.
I really enjoy MermaidJS. I've been trying to shoehorn representing vlan flows over switches recently and haven't been very successful. My basic goal is to show [p1]switch1[p2] <------> [p9]switch3[p12] in a graphical manner (and more intermediate switches). MermaidJS kind of works. I'm tempted to use something like Visio or Google Drawings but they take too much manual work.
I've gotten some mileage out of the PlantUML JSON visualization, as well as the REGEX graph, gantt, salt, and wbs for org charts.
XEARTH is also pretty neat, if you don't want to bring in a full mapping API just to show a point on a map. I realize it's a pretty crappy map in XEARTH, but the point is, I don't always need a good map.
Mermaid's nice though. I love the git graph - I use that thing every day. If I'm not dealing with ITAR data I just render everything remote through the kroki service, and take what I need from each graph spec.
Yes, there are many useful diagrams in UML, but a lot of them (e.g. entity diagrams) don't map well to text based formats such as MermaidJS, because the positioning is quite important and MermaidJS often won't guess correctly.
Meanwhile, sequence diagrams map very well from the text description.
I really like using Mermaid to create state diagrams. I'd been looking for a tool like it for quite some time, and I think it slipped under my radar because it's more focused on sequence / flow diagrams and doesn't hype its state diagram capabilities as much. Using a text-based tool for this is so much better than my previous workflow of Visio or Powerpoint.
Last time I tried this it unnecessarily crossed a lot of the arrows between states. Turned a diagram of a moderately complex real world SM into an incomprehensible tangle even to developers familiar with the actual implementation. Does it still do that?
Thanks for sharing! There's an updated viz at https://stately.ai/viz but that will soon be fully part of the studio at https://state.new (which can export to Mermaid now and PlantUML soon!)
Not the OP, but sequence diagrams show individual scenarios, by definition. And there can be a lot of scenarios in a complex system. Thousands, perhaps.
Relation (box-and-line) diagrams show the static relations between resources in a system, not individual scenarios. This typically gives a better overview.
- Thanks for the details and resources. Where is the "graph" in the post? When someone says graph I usually think of a pretty basic thing with nodes and edges.
I prefer D2 lang over MermaidJS for diagrams because the diagrams just "look" better and you have more ability to customise the look. And after all if the purpose is visualisation the visual matter.
I was going to ask why you don't have a web version but you already do. I'm going to play with this more today.
Have you thought about an "auto compile"/live mode where it changes as you edit the text? I think this adds a level of intuitiveness that would help new users explore.
I wish there were a CL/Clojure alternative to MermaidJS with a predictable interface so I could build diagrams at the REPL avoid searching/remembering what weird DSL to use when making diagrams. MermaidJS does seem to be a solid tool though. I use Omnigraffle when I want more control over the result.
MermaidJS is fantastic. I love that github has integrated it, but I wish they would update so that the markdown-in-mermaid support worked. If you agree, say so on the issue I posted: https://github.com/orgs/community/discussions/61266
I guess it’s effective because it is similar to Markdown and other lightweight stuff: things like bullet items are just written like bullet items, with hyphens (or similar). You write it how you want it to be displayed. Granted for a diagram it’s more complicated since it’s a graph and not a tree, and you write it with declarative arrows rather than as ASCII art, but perhaps that in practice strikes a nice balance between being non-finicky and at the same being simple enough (syntax-wise) in order to deal with.
That aside the “unreasonable effectiveness” allusion to “The Unreasonable Effectiveness of Mathematics in the Natural Sciences” is clearly overwrought. Let’s not get ahead of ourselves.
> Reaching for code to solve my code problem seemed like something that would only appeal to someone that loves code so much that they're probably no good at visualizing.
OP here, did not know of the existence of “The Unreasonable Effectiveness of Mathematics in the Natural Sciences”! I agree, that's a whole other level.
> That aside the “unreasonable effectiveness” allusion to “The Unreasonable Effectiveness of Mathematics in the Natural Sciences” is clearly overwrought. Let’s not get ahead of ourselves.
My point was it was no allusion to the original at all. The format took a life of its own, and is now a meme, and the author himself confirms it was the case in the sibling comment. No need to pull that scary ellipsis out.
Maybe I'm nuts because I've never found these useful. If you actually want to model a real-world scenario, you'll end with an arrow from every system to every other system to the point that it's meaningless as a visualization.
I'm thinking more about business processes rather than protocols. I don't think most project involve devising new protocols. If I want to diagram the steps involved in, say, onboarding and nurturing a user, then the flow will rapidly approach a cyclic, undirected graph.
Slight aside: does anyone know how mermaid/planutml layout functionality is implemented? I'd like to do something similar (but much simpler). I have a few entities (boxes) that are part of a DAG, and I'd like to lay them out somewhat optimally.
It's not the interesting problem that I'm trying to solve so I'd love to reuse something if I can.
A previous company I worked at had a way to translate logs into sequence diagrams - specifically in this case SIP message flow. by searching for an ID you could see all of the services which interacted with the message flow, and by clicking on the arrow a full version of the message which was sent.
It was amazingly useful for diagnosing problems. I wish more logging systems were able to visualise flows through a system of micro services so well!
I like Draw.io for UML but I recently found it easier to do a sequence diagram showing a Stripe integration with actors, activations and notes in a few lines of Mermaid markdown on a GitHub readme:
https://github.com/hbcondo/revenut-web#-workflow
But that diagram just renders as code via GitHub Pages:
Yes, this is what I use and I can't recommend it highly enough. I'll try mermaid but I think swimlanes.io is going to win for most use cases. Here's why:
(1) you just open the web app and start typing and you have the beginnings of your diagram within 30 seconds literally.
(2) The web app is elegantly and thoughtfully designed, the diagrams are beautiful, export functionality is there.
For your point (1) I can offer you https://sequence-diagrams.netlify.app which is my years-old quick diagramming tool for Mermaid and works similarly.
For your point (2) I offer the same alternative, but with the caveat that of the 3 criteria of elegant/thoughtful design, beautiful diagrams, and export functionality, it meets only the last 2 (and I claim little personal credit in any case).
> But I'm not aware of a reason why anyone wouldn't want to use swimlanes.io
Totally fair; personal preference. For me I could quite easily replace swimlanes in your comment with my own site, and I'm sure others would have alternatives that also seem an obvious first pick - there's rarely one size fits all.
I've used MermaidJS to create sequence diagrams for the project I'm working on and it helped tremendously in discovering what a heap of steaming manure I wrought.
112 comments
[ 0.31 ms ] story [ 192 ms ] threadThe syntax is a bit different though, so it depends on where your source is coming from, see here: https://text-to-diagram.com/?example=sequence&b=mermaid
However the big problem here being that d2 is still quite new and isn't as well supported as Mermaid JS
1. http://blockdiag.com/en/seqdiag/index.html
Mermaid needs a browser's layout engine to run properly [1], but I haven't yet seen a library that will help us without puppeteer.
And yep, NPM (or another Node.JS package manager) is still needed for installation. I was working on trying to bundle all of mermaid-cli's dependencies (aka Node.JS, puppeteer) into one massive single-file exe last weekend, but it's seems we're blocked by missing features in other packages [2].
If anyone has any ideas on how to implement these things easily, feel free to help-out :) I'm also not a big fan of puppeteer, so I'd love to see a way to go without it.
[1]: https://github.com/mermaid-js/mermaid/issues/3650
[2]: https://github.com/mermaid-js/mermaid-cli/issues/467#issueco...
---
Just to give you an idea of how hard this would be, Mermaid let's people use custom fonts, with fallbacks, so diagrams can look quite different depending on what font people have installed.
The current default font is Tahoma [4], which is owned by Microsoft, so Linux desktops usually render the diagrams slightly differently than on Windows/MacOS desktops.
People can also have different default font size in their browser/OS settings, and that will affect things too.
Finally, you also have things like ClearType [5], where the text is rendered differently depending on the sub-pixel arrangement of your monitor!!
I think we could get a basic version that partially works by implementing only a subset of the layout functions and hard-coding one specific font in, but even that would still be a fair bit of work.
[1]: https://drafts.csswg.org/cssom-view/#dom-element-getbounding...
[2]: https://github.com/jsdom/jsdom
[3]: https://github.com/jsdom/jsdom/issues/1322
[4]: https://en.wikipedia.org/wiki/Tahoma_(typeface)
[5]: https://en.wikipedia.org/wiki/ClearType
My guide: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...
The default styles in mermaid look a little nicer than graphviz, which might be enough to motivate me to try it out. When/if I do, I'll probably try with this emacs package: https://github.com/abrochard/mermaid-mode.
Docusaurus.io framework. Why? It's compatible with MermaidJS-- simply run 1 install command, and setup 2 config settings-- shown here: https://docusaurus.io/docs/next/api/themes/@docusaurus/theme...
Docusaurus provides: Docs, Blog, Pages. Via Markdown. And for pages, it even allows basic JSX (reactjs style components).
Lately I've really been enjoying the combination of Docusaurus & Mermaid to document my personal projects.
As a bonus, niolesk is a very good frontend on top of kroki. You get an editable link of your diagram which you can share with teammates.
You can find docker image on github running kroki and niolesk.
running directly in the browser is, imho, the best feature of mermaidjs
https://github.com/joelparkerhenderson/plantuml-examples
However, it gets to be difficult to use if you've got complicated scenarios. It's very difficult to depict parallelism with PlantUML.
And why do so many tools choose to ignore life lines and provide incomplete sequence diagrams? Perhaps it gets really complicated to express in such a simple way as the examples do?
https://plantuml.com/sequence-diagram#5cc0040514e70f7b
You can even have two active on the same lane at the same time, as shown in the second example on that page.
I'd use whichever works for your ecosystem and diagram lifecycle. The syntax is similar enough that I think the diagram creation constraints are often a bigger difference.
[0] https://github.com/plantuml-stdlib/C4-PlantUML
That being said, SVG is likely still a better option than PNG for its scalability alone. At least for this kind of content.
I only wish the renderer could render "sketch" style like Excalidraw, I don't like the default appearance. Obviously a small detail, though.
Entity diagrams, especially for database ERD
Timing diagrams (think: Gantt)
Interaction/flow diagrams
Use case diagrams
0 - https://www.uml-diagrams.org/deployment-diagrams.html
XEARTH is also pretty neat, if you don't want to bring in a full mapping API just to show a point on a map. I realize it's a pretty crappy map in XEARTH, but the point is, I don't always need a good map.
Mermaid's nice though. I love the git graph - I use that thing every day. If I'm not dealing with ITAR data I just render everything remote through the kroki service, and take what I need from each graph spec.
Meanwhile, sequence diagrams map very well from the text description.
Relation (box-and-line) diagrams show the static relations between resources in a system, not individual scenarios. This typically gives a better overview.
Long story short, you need both. If you want the long story, I wrote (a lot) on this a couple of years back: https://www.ilograph.com/blog/posts/the-two-fundamental-type...
- What're your thoughts on C4?
i hope it makes a bit more sense
(Shameless plug: Intro to D2 https://victorbjorklund.com/build-diagrams-as-code-with-d2-d... )
I was going to ask why you don't have a web version but you already do. I'm going to play with this more today.
Have you thought about an "auto compile"/live mode where it changes as you edit the text? I think this adds a level of intuitiveness that would help new users explore.
[0] https://forgejo.org
[1] https://github.com/abhinav/goldmark-mermaid
0: https://marketplace.atlassian.com/apps/1214124/mermaid-plugi...
That aside the “unreasonable effectiveness” allusion to “The Unreasonable Effectiveness of Mathematics in the Natural Sciences” is clearly overwrought. Let’s not get ahead of ourselves.
> Reaching for code to solve my code problem seemed like something that would only appeal to someone that loves code so much that they're probably no good at visualizing.
It looks more like a pseudo-markup to me.
Can I ask why you chose that title template?
It's a meme title, I've seen it a couple of times on HN: https://hn.algolia.com/?q=Unreasonable+Effectiveness
Also see: https://hn.algolia.com/?dateRange=all&page=0&prefix=true&que...
I don’t know how else you would model that. Words don’t communicate deeply enough.
It's not the interesting problem that I'm trying to solve so I'd love to reuse something if I can.
I have noticed that some tools don't allow exporting diagrams anymore or have a watermark on them now. Need to add that info someday.
It was amazingly useful for diagnosing problems. I wish more logging systems were able to visualise flows through a system of micro services so well!
[0] https://zipkin.io/ [1] https://opentelemetry.io/docs/
But that diagram just renders as code via GitHub Pages:
https://revenut.com
https://swimlanes.io/
(1) you just open the web app and start typing and you have the beginnings of your diagram within 30 seconds literally.
(2) The web app is elegantly and thoughtfully designed, the diagrams are beautiful, export functionality is there.
For your point (2) I offer the same alternative, but with the caveat that of the 3 criteria of elegant/thoughtful design, beautiful diagrams, and export functionality, it meets only the last 2 (and I claim little personal credit in any case).
Totally fair; personal preference. For me I could quite easily replace swimlanes in your comment with my own site, and I'm sure others would have alternatives that also seem an obvious first pick - there's rarely one size fits all.
That’s been so convenient to me, I now strongly prefer mermaidjs over more featured tools like lucid or Visio or draw.io.