The Unreasonable Effectiveness of Sequence Diagrams in MermaidJS | Hacker News Reader

The Unreasonable Effectiveness of Sequence Diagrams in MermaidJS

jessems.com

207 pointsjessems111 comments

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

https://plantuml.com/sequence-diagram

Cool, I'll check it out.

Checkout kroki as well which is collection of various tools including plantuml, tikz, mermaidjs, graphvi etc.

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.

I came to say the same thing; kroki is the powertool of choice in this space.

I believe PlantUML was basically the inspiration for MermaidJS. A huge advantage of MermaidJS is that it can run in the browser, though.

And if you start a markdown codeblock like

    ```mermaid
    graph TD;
      A-->B
    ```

Many things that support markdown (e.g. github, gitlab, typora, ...) will render the resulting graph.

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.

unfortunately, you need a PlanetUML server when using a self hosted gitlab install.

running directly in the browser is, imho, the best feature of mermaidjs

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.

More examples of sequence diagrams with PlantUML, with renderings of dividers, actors, databases, etc.:

https://github.com/joelparkerhenderson/plantuml-examples

I've used PlantUML. It's very nice.

However, it gets to be difficult to use if you've got complicated scenarios. It's very difficult to depict parallelism with PlantUML.

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?

It has those! They're under "Lifeline Activation and Destruction" on that page:

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 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.

PlantUML also has a nice library for C4 model diagrams available [0], which I've found very useful.

[0] https://github.com/plantuml-stdlib/C4-PlantUML

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.

It looks more like a pseudo-markup to me.

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.

A fine example of a meme spreading untethered from its source.

Can I ask why you chose that title template?

> 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.

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...

Yes, an allusion is indeed a kind of meme...

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.

(Shameless plug: Intro to D2 https://victorbjorklund.com/build-diagrams-as-code-with-d2-d... )

https://play.d2lang.com/?script=qlDQtVOo5AIEAAD__w%3D%3D&ske...

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

Forgejo [0] (and Gitea) have also implemented it. Or more accurate to say, they use Goldmark markdown parser and the Mermaid extension [1].

[0] https://forgejo.org

[1] https://github.com/abhinav/goldmark-mermaid

I really, _really_ wish I could generate SVGs of these without JavaScript and a headless browser.

The mmdc tool does this!

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.

Have you looked at d2lang - it supports SVG output: https://d2lang.com/tour/exports/

The 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

I really like d2 a lot more than its alternatives.

However the big problem here being that d2 is still quite new and isn't as well supported as Mermaid JS

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.

1. http://blockdiag.com/en/seqdiag/index.html

As another commenter mentions, the mmdc tool takes care of this. I should have mentioned that in the blog post.

Does it do it without needing to have npm and puppeteer installed at all?

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.

[1]: https://github.com/mermaid-js/mermaid/issues/3650

[2]: https://github.com/mermaid-js/mermaid-cli/issues/467#issueco...

Why is it so difficult to do the layout yourself and generate SVG directly?

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.

[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

D2 lang (https://d2lang.com) can do that.

My guide: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

Curious if anyone has experience with large diagrams (100K+ elements) using D2 or something similar?

I've had a lot of luck with Graphviz and ridiculous numbers of nodes. Have you tried that?

A little bit, I'm just not a fan of the way it looks.

That's a perfectly fair issue. Mermaid and friends are soooo much prettier.

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.

Hah, I haven't tried that, but I bet it's possible to do it all within org-mode...

I have used https://github.com/mermaid-js/mermaid-cli

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.

Have you tried draw.io?

An alternative to using Marky to render the Mermaid diagram which I did not see anyone mention is this VS Code plug-in. I use it and it is quite nice:

https://marketplace.visualstudio.com/items?itemName=bierner....

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.

Likewise. I also really like being able to quickly diff diagram versions to quickly see what is new since the last version.

That’s been so convenient to me, I now strongly prefer mermaidjs over more featured tools like lucid or Visio or draw.io.

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!

For microservice tracing, you might want to look at Zipkin [0], or OpenTelemetry [1]

[0] https://zipkin.io/ [1] https://opentelemetry.io/docs/

I wonder if the URL in the article to Marky shouldn't point to https://lib.rs/crates/marky instead of to the NPM package.

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.

Swimlanes is a simple implementation of the same concept.

https://swimlanes.io/

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).

That looks like a fun project! But I'm not aware of a reason why anyone wouldn't want to use swimlanes.io.

> 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.

For an easy, out of the block, self-hosted experience, allow me to recommend:

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.

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:

https://revenut.com

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.

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 haven't run into that, but maybe that's just because I haven't tried anything too complex yet.

Have you seen xstate's visualizer? https://xstate.js.org/viz/

I hadn't seen that, thanks for the link.

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!)

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.

Have you tried templates?

The article claims that sequence charts are the only useful thing in UML. What about:

Entity diagrams, especially for database ERD

Timing diagrams (think: Gantt)

Interaction/flow diagrams

Use case diagrams

Agreed. I'd also add deployment diagrams[0] to the "pretty darn useful" list.

0 - https://www.uml-diagrams.org/deployment-diagrams.html

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'll give those another look, thanks!

As an aside, I've been pretty impressed at GPT4's ability at generating MermaidJS sequence diagrams for open source projects.

Multiple comments like this, I'll try that out!

I'm a huge fan of riffing on architecture ideas, with chatgpt/GPT4, and then asking asking for a representation in mermaid syntax.

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 think you’re nuts :) I find them super helpful for refreshing when I need to see the flow for protocol exchanges like SIP, FTP, TLS.

I don’t know how else you would model that. Words don’t communicate deeply enough.

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.

My own quick and easy Mermaid diagramming page I knocked up a few years ago and stuck on Netlify, and which I (and a few others) use very frequently:

https://sequence-diagrams.netlify.app

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.

A list (that I occasionally update) of similar text-to-diagram tools that work from browser https://xosh.org/text-to-diagram/

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.

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.

If you use Notion, it supports MermaidJS as a comment block. It auto-update the generated diagram in real-time. Super useful.

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.

adding links + tooltips: https://jsfiddle.net/s37cjoau/3/

I did an eval of some other options for more dynamic apps including react-flow, cytoscapeJS etc. https://github.com/dcsan/autoapps/issues/1

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.

The popularity of MermaidJS makes me wonder why I cannot have that natively in Confluence.

I wonder why Confluence doesn’t include popular features all the time.

Confluence has a mermaid js plugin [0]. This is in fact why I switched from plantuml to mermaid.

0: https://marketplace.atlassian.com/apps/1214124/mermaid-plugi...

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...

Also lack of consistency in common things.

You probably shouldn't convert diagrams from HTML to PNGs since you lose all accessibility. SVGs might be better; I'm actually not at sure.

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.

Your meta tags need a little updating, they are still the generic ones: "Next.js Blog Starter Kit" .. same for description.

Github Markdown supports Mermaid OOTB, really useful.

i love mermaid but i find sequence diagrams too thin on information, a graph view always feels like the right amount of data

Please elaborate. The amount of information provided is up to the creator of the diagram...

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.

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...

- 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.

- What're your thoughts on C4?

a sequence is a projection of many interactions between modules, which can often be described fine on a 2d graph

i hope it makes a bit more sense

Reply on news.ycombinator.com