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
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).
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.
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.
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?
+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.
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.
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.
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.
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
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.
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.
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.
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.
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.
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 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.
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 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.
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 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:
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 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.
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!)
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?
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'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.
It's crazy how normalized powerful LLMs became this year. They still seem almost magical, but they're so accesible and commonplace they lost their novelty factor too fast.
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.
Note the credit on that page to bramp.github.io who did the hard work with the JS library it uses. And when you find UI issues remember it was a quick tool knocked up years ago and forgive me.
Before I switched to Obsidian for note taking, I'd been using UMLet (for some 20 years!) for all my UML needs. Its syntax for sequence diagrams is similar to Mermaid's. But now that I'm using Obsidian, I've switched to Mermaid. I see some people mentioning PlantUML, but I rather dislike that it required a rendering service last I tried to tinker with it. Mermaid does not.
I've had a good time with sequence diagrams in college. It is really pleasing to build them.
I entertain the idea that AI [CNN + TNN] can finally fulfill the ultimate UML promise: build code from diagrams. In a certain way, it's easy to see AI trained to ingest diagrams as logical sequences of prompts. With a little effort it is already doable with current tech.
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.
Alright I guess I’ll start learning Mermaid diagrams. I’ve loved the run that Heptone’s Monodraw had for my README diagrams, but, as a team, it requires too much:
- in order to edit/create effectively you have to purchase a license
- you have to own a Mac to edit/create effectively
I think the article links to the wrong marky library. The one linked to is a node lib called marky-mark, which does not appear to support mermaid. I think the correct link is this: https://docs.rs/crate/marky
I highly recommend https://swimlanes.io/ personally. It has essentially zero friction between thinking of a diagram and seeing the diagram in front of your eyes.
I'm sure Mermaid.js is nice and I will try it for comparison soon.
mermaid is mostly client side rendered in JS, so it's surprising it doesn't have a very well fleshed out API to handle interactivity. Also it's a pain to render to PNGs, you need a full headless browser/puppeteer to run mermaid-cli.
It's also handy that because its text based, generative AI can create the diagrams for you based off of a text description, which reduces the barrier to entry even more as you don't need to memorize the syntax to begin utilizing it.
In general I'm fan of text based diagramming tools, but with all mermaid diagrams that I've tried to do (flowchart, class diagram), you hit syntax limitations way too early...
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.
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.
