The Unreasonable Effectiveness of Sequence Diagrams in MermaidJS

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&#x27;t worry about every last silly detail that&#x27;s specified in the standard).<p><pre><code> @startuml Alice -&gt; Bob: Authentication Request Bob --&gt; Alice: Authentication Response Alice -&gt; Bob: Another authentication Request Alice &lt;-- Bob: Another authentication Response @enduml </code></pre> <a href="https:&#x2F;&#x2F;plantuml.com&#x2F;sequence-diagram" rel="nofollow noreferrer">https:&#x2F;&#x2F;plantuml.com&#x2F;sequence-diagram</a>

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.<p>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.<p>&gt; Reaching for code to solve my code problem seemed like something that would only appeal to someone that loves code so much that they&#x27;re probably no good at visualizing.<p>It looks more like a pseudo-markup to me.

I prefer D2 lang over MermaidJS for diagrams because the diagrams just &quot;look&quot; better and you have more ability to customise the look. And after all if the purpose is visualisation the visual matter.<p>(Shameless plug: Intro to D2 <a href="https:&#x2F;&#x2F;victorbjorklund.com&#x2F;build-diagrams-as-code-with-d2-d2lang" rel="nofollow noreferrer">https:&#x2F;&#x2F;victorbjorklund.com&#x2F;build-diagrams-as-code-with-d2-d...</a> )

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: <a href="https:&#x2F;&#x2F;github.com&#x2F;orgs&#x2F;community&#x2F;discussions&#x2F;61266">https:&#x2F;&#x2F;github.com&#x2F;orgs&#x2F;community&#x2F;discussions&#x2F;61266</a>

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

I really enjoy MermaidJS. I&#x27;ve been trying to shoehorn representing vlan flows over switches recently and haven&#x27;t been very successful. My basic goal is to show [p1]switch1[p2] &lt;------&gt; [p9]switch3[p12] in a graphical manner (and more intermediate switches). MermaidJS kind of works. I&#x27;m tempted to use something like Visio or Google Drawings but they take too much manual work.

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:<p><a href="https:&#x2F;&#x2F;marketplace.visualstudio.com&#x2F;items?itemName=bierner.markdown-mermaid" rel="nofollow noreferrer">https:&#x2F;&#x2F;marketplace.visualstudio.com&#x2F;items?itemName=bierner....</a>

I&#x27;ve used MermaidJS to create sequence diagrams for the project I&#x27;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.<p>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 wonder if the URL in the article to Marky shouldn&#x27;t point to <a href="https:&#x2F;&#x2F;lib.rs&#x2F;crates&#x2F;marky" rel="nofollow noreferrer">https:&#x2F;&#x2F;lib.rs&#x2F;crates&#x2F;marky</a> instead of to the NPM package.

I wish there were a CL&#x2F;Clojure alternative to MermaidJS with a predictable interface so I could build diagrams at the REPL avoid searching&#x2F;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.<p><a href="https:&#x2F;&#x2F;swimlanes.io&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;swimlanes.io&#x2F;</a>

For an easy, out of the block, self-hosted experience, allow me to recommend:<p>Docusaurus.io framework. Why? It&#x27;s compatible with MermaidJS-- simply run 1 install command, and setup 2 config settings-- shown here: <a href="https:&#x2F;&#x2F;docusaurus.io&#x2F;docs&#x2F;next&#x2F;api&#x2F;themes&#x2F;@docusaurus&#x2F;theme-mermaid" rel="nofollow noreferrer">https:&#x2F;&#x2F;docusaurus.io&#x2F;docs&#x2F;next&#x2F;api&#x2F;themes&#x2F;@docusaurus&#x2F;theme...</a><p>Docusaurus provides: Docs, Blog, Pages. Via Markdown. And for pages, it even allows basic JSX (reactjs style components).<p>Lately I&#x27;ve really been enjoying the combination of Docusaurus &amp; Mermaid to document my personal projects.

I like Draw.io for UML but I recently found it <i>easier</i> 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: <a href="https:&#x2F;&#x2F;github.com&#x2F;hbcondo&#x2F;revenut-web#-workflow">https:&#x2F;&#x2F;github.com&#x2F;hbcondo&#x2F;revenut-web#-workflow</a><p>But that diagram just renders as code via GitHub Pages:<p><a href="https:&#x2F;&#x2F;revenut.com" rel="nofollow noreferrer">https:&#x2F;&#x2F;revenut.com</a>

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&#x27;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&#x27;d been looking for a tool like it for quite some time, and I think it slipped under my radar because it&#x27;s more focused on sequence &#x2F; flow diagrams and doesn&#x27;t hype its state diagram capabilities as much. Using a text-based tool for this is <i>so much</i> better than my previous workflow of Visio or Powerpoint.

I have used Mermaid diagrams quite a bit lately because ChatGPT can generate them. It&#x27;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&#x27;t!<p>I only wish the renderer could render &quot;sketch&quot; style like Excalidraw, I don&#x27;t like the default appearance. Obviously a small detail, though.

The article claims that sequence charts are the only useful thing in UML. What about:<p>Entity diagrams, especially for database ERD<p>Timing diagrams (think: Gantt)<p>Interaction&#x2F;flow diagrams<p>Use case diagrams

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

Maybe I&#x27;m nuts because I&#x27;ve never found these useful. If you actually want to model a real-world scenario, you&#x27;ll end with an arrow from every system to every other system to the point that it&#x27;s meaningless as a visualization.

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:<p><a href="https:&#x2F;&#x2F;sequence-diagrams.netlify.app" rel="nofollow noreferrer">https:&#x2F;&#x2F;sequence-diagrams.netlify.app</a><p>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&#x27;d been using UMLet (for some 20 years!) for all my UML needs. Its syntax for sequence diagrams is similar to Mermaid&#x27;s. But now that I&#x27;m using Obsidian, I&#x27;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&#x27;ve had a good time with sequence diagrams in college. It is really pleasing to build them.<p>I entertain the idea that AI [CNN + TNN] can finally fulfill the ultimate UML promise: build code from diagrams. In a certain way, it&#x27;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 <a href="https:&#x2F;&#x2F;xosh.org&#x2F;text-to-diagram&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;xosh.org&#x2F;text-to-diagram&#x2F;</a><p>I have noticed that some tools don&#x27;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&#x2F;planutml layout functionality is implemented? I&#x27;d like to do something similar (but much simpler). I have a few entities (boxes) that are part of a DAG, and I&#x27;d like to lay them out somewhat optimally.<p>It&#x27;s not the interesting problem that I&#x27;m trying to solve so I&#x27;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&#x2F;create effectively you have to purchase a license - you have to own a Mac to edit&#x2F;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: <a href="https:&#x2F;&#x2F;docs.rs&#x2F;crate&#x2F;marky" rel="nofollow noreferrer">https:&#x2F;&#x2F;docs.rs&#x2F;crate&#x2F;marky</a>

I highly recommend <a href="https:&#x2F;&#x2F;swimlanes.io&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;swimlanes.io&#x2F;</a> personally. It has essentially zero friction between thinking of a diagram and seeing the diagram in front of your eyes.<p>I&#x27;m sure Mermaid.js is nice and I will try it for comparison soon.

mermaid is mostly client side rendered in JS, so it&#x27;s surprising it doesn&#x27;t have a very well fleshed out API to handle interactivity. Also it&#x27;s a pain to render to PNGs, you need a full headless browser&#x2F;puppeteer to run mermaid-cli.<p>adding links + tooltips: <a href="https:&#x2F;&#x2F;jsfiddle.net&#x2F;s37cjoau&#x2F;3&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;jsfiddle.net&#x2F;s37cjoau&#x2F;3&#x2F;</a><p>I did an eval of some other options for more dynamic apps including react-flow, cytoscapeJS etc. <a href="https:&#x2F;&#x2F;github.com&#x2F;dcsan&#x2F;autoapps&#x2F;issues&#x2F;1">https:&#x2F;&#x2F;github.com&#x2F;dcsan&#x2F;autoapps&#x2F;issues&#x2F;1</a>

It&#x27;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&#x27;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.

In general I&#x27;m fan of text based diagramming tools, but with all mermaid diagrams that I&#x27;ve tried to do (flowchart, class diagram), you hit syntax limitations way too early...<p>Also lack of consistency in common things.

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

Your meta tags need a little updating, they are still the generic ones: &quot;Next.js Blog Starter Kit&quot; .. 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