11 ms·
The Unreasonable Effectiveness of Sequence Diagrams in MermaidJS
- WirelessGigabit 3y agoThe popularity of MermaidJS makes me wonder why I cannot have that natively in Confluence.
- pjot 3y agoI wonder why Confluence doesn’t include popular features all the time.
- tra3 3y agoConfluence 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-plugin-for-confluence?tab=overview&hosting=server https://marketplace.atlassian.com/apps/1214124/mermaid-plugi...
- dpflan 3y agoI 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).
- rcarmo 3y agoI really, _really_ wish I could generate SVGs of these without JavaScript and a headless browser.
- pbnjay 3y agoThe mmdc tool does this!
- rcarmo 3y agoI'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.
- jrmiii 3y agoHave you looked at d2lang - it supports SVG output: https://d2lang.com/tour/exports/ 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 https://text-to-diagram.com/?example=sequence&b=mermaid
- sp33der89 3y agoI 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
- gpderetta 3y agoHaving 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.
- hiyer 3y agoCheck 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 http://blockdiag.com/en/seqdiag/index.html
- jessems 3y agoAs another commenter mentions, the mmdc tool takes care of this. I should have mentioned that in the blog post.
- rcarmo 3y agoDoes it do it without needing to have npm and puppeteer installed at all?
- aloisklink 3y agoI'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 https://github.com/mermaid-js/mermaid/issues/3650 [2]: https://github.com/mermaid-js/mermaid-cli/issues/467#issuecomment-1646720045 https://github.com/mermaid-js/mermaid-cli/issues/467#issueco...
- andrewshadura 3y agoWhy is it so difficult to do the layout yourself and generate SVG directly?
- ygra 3y agoMy 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.
- victorbjorklund 3y agoD2 lang (https://d2lang.com https://d2lang.com) can do that. My guide: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d2lang https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...
- rgrieselhuber 3y agoCurious if anyone has experience with large diagrams (100K+ elements) using D2 or something similar?
- kstrauser 3y agoI've had a lot of luck with Graphviz and ridiculous numbers of nodes. Have you tried that?
- rgrieselhuber 3y agoA little bit, I'm just not a fan of the way it looks.
- kstrauser 3y agoThat's a perfectly fair issue. Mermaid and friends are soooo much prettier.
- hoosieree 3y agoCurrently 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 https://github.com/abrochard/mermaid-mode.
- nequo 3y agoHave 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.
- hoosieree 3y agoHah, I haven't tried that, but I bet it's possible to do it all within org-mode...
- ree-san 3y agoI have used https://github.com/mermaid-js/mermaid-cli https://github.com/mermaid-js/mermaid-cli
- jimmychoozyx 3y agoFor 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-mermaid 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.
- Pirate-of-SV 3y agoGithub Markdown supports Mermaid OOTB, really useful.
- quietbritishjim 3y agoI 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 https://plantuml.com/sequence-diagram
- jessems 3y agoCool, I'll check it out.
- dilawar 3y agoCheckout 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.
- chrisweekly 3y agoI came to say the same thing; kroki is the powertool of choice in this space.
- The_Colonel 3y agoI believe PlantUML was basically the inspiration for MermaidJS. A huge advantage of MermaidJS is that it can run in the browser, though.
- atoav 3y agoAnd 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.
- Veuxdo 3y agoYou probably shouldn't convert diagrams from HTML to PNGs since you lose all accessibility. SVGs might be better; I'm actually not at sure.
- ygra 3y agoWhen 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.
- williamdclt 3y agoIf you use Notion, it supports MermaidJS as a comment block. It auto-update the generated diagram in real-time. Super useful.
- kristiandupont 3y agoI 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.
- jessems 3y agoHave you tried templates?
- client4 3y agoI 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.
- jaktet 3y agoHave you tried draw.io?
- ttfkam 3y agoThe 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
- AdieuToLogic 3y agoAgreed. I'd also add deployment diagrams[0] to the "pretty darn useful" list. 0 - https://www.uml-diagrams.org/deployment-diagrams.html https://www.uml-diagrams.org/deployment-diagrams.html
- MilStdJunkie 3y agoI'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.
- The_Colonel 3y agoYes, 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.
- jessems 3y agoI'll give those another look, thanks!
- mrWiz 3y agoI 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.
- giraffe_lady 3y agoLast 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?
- mrWiz 3y agoI haven't run into that, but maybe that's just because I haven't tried anything too complex yet.
- chrisweekly 3y agoHave you seen xstate's visualizer? https://xstate.js.org/viz/ https://xstate.js.org/viz/
- mrWiz 3y agoI hadn't seen that, thanks for the link.
- davidkpiano 3y agoThanks for sharing! There's an updated viz at https://stately.ai/viz https://stately.ai/viz but that will soon be fully part of the studio at https://state.new https://state.new (which can export to Mermaid now and PlantUML soon!)
- agumonkey 3y agoi love mermaid but i find sequence diagrams too thin on information, a graph view always feels like the right amount of data
- dpflan 3y agoPlease elaborate. The amount of information provided is up to the creator of the diagram...
- Veuxdo 3y agoNot 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-types-of-architecture-diagrams/ https://www.ilograph.com/blog/posts/the-two-fundamental-type...
- dpflan 3y ago- 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?
- agumonkey 3y agoa 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
- victorbjorklund 3y agoI 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-d2lang https://victorbjorklund.com/build-diagrams-as-code-with-d2-d... )
- pragmatic 3y agohttps://play.d2lang.com/?script=qlDQtVOo5AIEAAD__w%3D%3D&sketch=1& 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.
- BaculumMeumEst 3y agoI 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.
- foobarbecue 3y agoMermaidJS 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 https://github.com/orgs/community/discussions/61266
- rapnie 3y agoForgejo [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 https://forgejo.org [1] https://github.com/abhinav/goldmark-mermaid https://github.com/abhinav/goldmark-mermaid
- rapnie 3y agoI wonder if the URL in the article to Marky shouldn't point to https://lib.rs/crates/marky https://lib.rs/crates/marky instead of to the NPM package.
- nativecoinc 3y agoI 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.
- jessems 3y agoOP 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.
- nh23423fefe 3y agoA fine example of a meme spreading untethered from its source. Can I ask why you chose that title template?
- urxvtcd 3y ago> 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 https://hn.algolia.com/?q=Unreasonable+Effectiveness Also see: https://hn.algolia.com/?dateRange=all&page=0&prefix=true&query=stop+worrying+and+love&sort=byPopularity&type=story https://hn.algolia.com/?dateRange=all&page=0&prefix=true&que...
- nativecoinc 3y ago
- tootie 3y agoMaybe 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.
- bnjms 3y agoI 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.
- tootie 3y agoI'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.
- tra3 3y agoSlight 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.
- smusamashah 3y agoA list (that I occasionally update) of similar text-to-diagram tools that work from browser https://xosh.org/text-to-diagram/ 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.
- NeoTar 3y agoA 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!
- tincholio 3y agoFor microservice tracing, you might want to look at Zipkin [0], or OpenTelemetry [1] [0] https://zipkin.io/ https://zipkin.io/ [1] https://opentelemetry.io/docs/ https://opentelemetry.io/docs/
- hbcondo714 3y agoI 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 https://github.com/hbcondo/revenut-web#-workflow But that diagram just renders as code via GitHub Pages: https://revenut.com https://revenut.com
- mrblues 3y agoSwimlanes is a simple implementation of the same concept. https://swimlanes.io/ https://swimlanes.io/
- deleted 3y ago[deleted]
- da39a3ee 3y agoYes, 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.
- kcartlidge 3y agoFor your point (1) I can offer you https://sequence-diagrams.netlify.app 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).
- da39a3ee 3y agoThat looks like a fun project! But I'm not aware of a reason why anyone wouldn't want to use swimlanes.io.
- kcartlidge 3y ago> 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.
- Tade0 3y agoI'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.
- prepend 3y agoLikewise. 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.
- neuronexmachina 3y agoAs an aside, I've been pretty impressed at GPT4's ability at generating MermaidJS sequence diagrams for open source projects.
- jessems 3y agoMultiple comments like this, I'll try that out!
- crftr 3y agoI'm a huge fan of riffing on architecture ideas, with chatgpt/GPT4, and then asking asking for a representation in mermaid syntax.
- ASalazarMX 3y agoIt'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.
- macmac 3y agoI 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 https://docs.rs/crate/marky
- da39a3ee 3y agoI highly recommend https://swimlanes.io/ 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.
- hcrisp 3y agoAn 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.markdown-mermaid https://marketplace.visualstudio.com/items?itemName=bierner....
- galkk 3y agoIn 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.
- Vox_Leone 3y agoI'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.
- w_for_wumbo 3y agoIt'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.
- elric 3y agoBefore 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.
- petercooper 3y agoYour meta tags need a little updating, they are still the generic ones: "Next.js Blog Starter Kit" .. same for description.
- dcsan 3y agomermaid 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/ 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 https://github.com/dcsan/autoapps/issues/1
- alanwreath 3y agoAlright 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
- kcartlidge 3y agoMy 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 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.