IMO mermaid is awesome, but for two somewhat indirect reasons:
- There’s an almost wysiwig editor for mermaid at https://www.mermaidchart.com/play . It’s very convenient and appropriately changes the layout as you draw arrows!
- Notion supports inline mermaid charts in code blocks (with preview!) It’s awesome for putting some architecture diagrams in Eng docs.
LLMs (I use ChatGPT) can take a generic process description, spit out the result in mermaid, which can then be imported and refined in something like draw.io. Yes, you’ll have to correct a few things by hand, but it drastically speeds things up. Last time I check draw.io is supported in obsidian.
One of my favorite applications of multimodal LLMs thus far is the ability to:
1. Draw a DAG of whatever pipeline I’m working on with pen and paper.
2. Take a photo of the graph, mistakes and all.
3. Ask ChatGPT to translate the image into mermaid.js
Given how complicated the pipelines are that I’m working with and the sloppiness of the hand drawn image, it’s truly amazing how well this workflow works.
I recently did a variation of this where instead of drawing, I just drafted a quick few bullet points and text describing at a high level what the system should do. And then I asked chat GPT to identify use cases and generate sequence diagrams for each use case in puml format (plantuml). Shockingly effective and it took about five minutes. This was a technical proposal that I shared with a few partner companies to provide a detailed plan to a customer. It came after several online meetings spaced over a few weeks of us negotiating the details. Pretty important document and it was well received. Plantuml looks decent enough that you can get away with sticking the resulting diagrams in a document.
I'm a busy person. I don't have hours of time that I can take out of my schedule to generate what I regard as write only documentation (nobody will ever read or truly value it) that ticks the box of "we have stuff to point at when somebody asks (which nobody ever will)", which has a lowish value. Sometimes it's nice to have. The above is a fine example. People will glance at it, give me a little thumbs up, and then give me permission to proceed as planned and bill accordingly. Job done. It's not a reference design that anyone will ever look at for more than a few seconds.
After a few decades in the industry, I'm extremely skeptical of the value of diagrams vs. the time required to produce them. I just don't see it. A lot of good software gets produced without them. You don't need blueprints for your blueprints, which is what source code is (a blueprint for automatically compiling into working software). People value such traits as structure, readability, conciseness in source code for a reason: it allows them to treat source code as design assets. I don't write UML, I stub out data classes and interfaces instead. And then I refactor them over and over again. Diagrams just slow me down.
But a few minutes is about on the threshold of me wasting braincycles on producing them and enrich documentation that I'm writing anyway in text form. Quickly jot down some notes. Don't waste any time whatsoever obsessing about the awkward syntax of these micro languages, and just get the essentials nailed. I bet I can get it down to like a minute or so with better LLMs and larger context windows. "Examine this project, produce an overview diagram of all the database tables". That's a prompt I'd write. In the same way, letting LLMs document code is a great use of time.
> write only documentation (nobody will ever read or truly value it)
But what's the point of producing such documentation? I could imagine that the process of creating it could be somehow beneficial (committing to memory, finding discrepancies, etc). If it's not, why can't it just be skipped?
Documentation is a tool for creating shared understanding. If you don’t need to share your understanding, don’t write docs.
Note however that sharing understanding works on the people axis and on the time axis. Docs allow you to share your current understanding with your future self. They’d better be general enough to be true then, though.
Nowadays I find Gemini pro to be able to accurately document a complex workflow within minutes just by looking at the sources and sometimes even just logs, so value of low level docs is questionable. High level requirements - essentially how it’s supposed to work and what for - is very valuable, as it allows you and the model to cross check whether things work as they were intended.
None other than ticking boxes and shutting up the people that keep asking for such things to be produced. Who then invariably don't have the attention span to do anything with the diagram. That's literally the only reason I have for creating them. Otherwise it's a tedious activity that gets in the way of developing, slows me down, and just interrupts my creative process. I usually have better things to do.
And as you might understand from what I just said, I rarely produce any diagrams. I've been active as a developer since before UML got popular and then peaked and then faded into obscurity. I still have a signed (by Martin Fowler) copy of UML distilled on a shelf somewhere gathering dust. First edition and everything. I don't think it's very valuable. Waste paper basically. But contact me if you feel otherwise. It's in pristine condition because I never did much more than thumb though it and shelve it.
25 years ago, any self respecting architect had expensive licenses for things like rational rose or visio. And they'd be fiddling with those tools for hours to produce detailed class and other diagrams. And those diagrams were as useless then as they are now. Epic waste of time. People stopped buying and using those tools. This was once a very big industry that has now imploded to next to nothing. Nobody is buying, very few people waste budget on this crap. It's a niche market with some niche revenue. Tens of millions of developers ignore these tools.
What do plantuml, mermaid, and other OSS diagramming tools have in common? The people that make them don't eat their own dogfood to document how their own software works. You can have some fun looking for diagrams in OSS projects. With few exceptions, this is not a thing (devops people seem to have a weird obsession with diagramming. And overengineering). I'm not aware of many serious OSS project where developers have bothered to document even a tiny fraction of their software with diagrams. Including all the major OSS UML diagramming tools.
The documentation for these contains plenty of examples of course (typically very simplistic). Just not any that document how the tool is designed or works. I'm not judging. I wouldn't bother either for reasons that I articulated above. But I find it ironic that even diagram tool developers don't seem to feel an urge to use diagrams for their own stuff. Makes you wonder why they bother creating the tool? You'd have to be passionate about diagramming tools but not so that you'd want to use them for your own software.
I just used Mermaid for multiple sequence diagrams from build-steps sequences in a video talk I did on comparing build systems - https://www.youtube.com/watch?v=L67ri_xe2oQ (slides - https://paulhammant.com/google-style-dag-build-systems/). The new boost for me was GPT4o. It was able to quickly make what I wanted from the build logs alone, though it took some hand tweaking too. A new (or very old) problem after that was not taking sufficient save points (URL bookmarks) and sometimes making the same edit twice cos I'd lost a URL. That there was a second save of the PNG form for each (https://kroki.io/mermaid/svg/...) added to the keep-track-of-changes problem for me, especially when I'm very tired me :(
Check out Kroki for a multi-syntax wrapper around a bunch of text driven diagram generators —- including Mermaid, PlantUML, Ditaa, GraphViz, SVGBob, etc, etc
I'm slightly surprised excalidraw (https://excalidraw.com/) is not in the comments. I use it regularly to convey ideas to my devs and designers. Plus, it exports to json! Someone wrote a library to convert mermaid to excalidraw as well.
We're now experimenting with creating design questions to ask in interviews with excalidraw/mermaid
I love excalidraw. But does it have an editable, diffable textual representation? Can it be generated with little ceremony, and laid out automatically?
I did a system design interview awhile back using Excalidraw. I really enjoyed it (though I also frequently use it for normal work stuff, so was familiar with it).
> Proprietary layout engine developed by Terrastruct
> TALA is a separate install from D2, to keep a clean cut between 100% free and open-source D2, and proprietary, closed-source TALA.
The two non-proprietary layout engines are 1) Dagre, a port of ideas from Graphviz to Javascript, where the only benefit over Graphviz seems to be "it's in Javascript!" 2) ELK, a fairly naive layout engine that makes non-symmetrical graphs with oddly crooked lines.
It's not too bad if you're prepared to set up a rendering pipeline using a static site generator like mkdocs. This will get you much better results than just letting GitHub et al render markdown in whatever style they please.
I don't love Mermaid and generally find it less well designed than something like Graphviz/dot. I generally find a lot of the syntax needlessly strict for something non-programmer humans are meant to interact with, but the big seller for me with Mermaid is that it works inline on GitHub.
I end up creating a lot of sequence diagrams and having them as editable mermaid is very convenient. I do wish GitHub giant mermaid navigation controls floating over the bottom right corner obscuring things.
I use it and see it many times per month as it’s the preferred way of sticking graphics and diagrams in markdown in git repos and generated static sites.
It’s so handy for putting a sequence diagram in your docs and then tracking the changes over time using git.
I’m curious what other software developers use if not this. I’ve tried specific graph and drawing tools like lucid and Visio, but the simplicity of mermaid is nice. And I don’t know anything else that shows git blame for who changed what in my diagram, when.
Re what other developers use. I tried mermaid and other text to diagram tools for work, but, as mentioned above, found them lacking. Most companies / teams I know of use something like excalidraw or miro. Definitely matches your simplicity requirements, but, obviously, no git blame
I love it when this happens, people almost always reply with something cool they did with it, or discovered. The link isn't new, often the comments are.
I love Mermaid diagrams. I let my coding LLMs generate diagrams during architecture design and then afterward for accuracy— Sequence Diagrams, CSD’s, Flowcharts, DFDs, and ERDs. Couldn’t be simpler. I’m happy.
This is built into Obsidian, and I love it for making quick diagrams in my notes.
Mapping out database tables while I’m conceptualizing an idea is what I use it more most often. I also use sequence diagrams to map process flow or try e flow of information.
I remember I use this last year when trying to draw my auth flow. I tried using excalidraw but it gets laggy if your chart is too big, besides I find it easier to type the chart than using the mouse.
Picking anything but PlantUML's default theme will make PlantUML look less 90's-Java. As a minimalistic solution, I already like "skinparam monochrome true" https://plantuml.com/skinparam#:~:text=Black%20and%20White. (You can go further with CSS and themes and...)
Another comment mentioned along the lines of, "it's the goto used by developers in readmes", and I suspect it's more specifically javascript-adjacent developers (as is the case where I work)
The "render locally" situation was enough friction to keep me happy with my .jpgs and .pngs generated from various sources and/or screenshotting.
I don't know if this helps you but the Mermaid plugin in JetBrains has an export feature which can save you a step. But I find Mermaid diagrams so limiting and the syntax more immature than PlantUML so it's very rare that I bother
The "in readmes" is a special case because the markdown rendering in both GitHub and GitLab support it without drama
Hmm. I thought I'd tried that but perhaps I didnt' read the documentation close enough. Even after reading your reply it took me about 20 minutes to realize the subgraph has to have a name prefix of "cluster." And after more digging I see now that cluster=true will do it as well.
It's not exactly what I was hoping for, but is an improvement on the randomization I had going on before!
I liked Mermaid but unfortunately LLMs don't understand it well, so I switched to Latex tikz which LLMs know pretty well. At least I know Gemini 2.5 Pro does a good job at tikz. 3.7 and o1 were meh.
I have an almost exhaustive list [1] of browser based text to diagram tools. Some specialised tools (like https://sequencediagram.org/) so much better at what they do than any generic ones like mermaid.
I wish WebSequenceDiagrams was further up your list. I guess I have some work to do.
When I made it, nothing like mermaid, plantUML，lucid charts existed. The syntax of most tools was based on Java or graphviz and overly verbose. I was writing an email to a colleague at BlackBerry and wrote out the sequence diagrams as text. I spent the next week making a script to convert it to an image and put it online. Many other tools have since adopted the syntax and I'm happy it has become so widespread.
Great tech - thanks for your pioneering work. I made https://vsm-book.com/app as a tool to support a meeting and leave a lasting artifact. WebSequenceDiagrams (and https://bramp.github.io/js-sequence-diagrams/ which also credits yours) was very much in my mind, though my grammer is much less elegant.
WebSequenceDiagrams has been my go to for years, and I'd be basically brainstorming straight in it in lieu of pen and paper. I laughed the day one of my colleague was explaining his issue on the whiteboard and he was writing it "A->B: some action" style instead of the actual box and arrow sequence, it just became part of our culture I think.
I had to move on when I couldn't get it approved at the place I worked, and nowadays PlantUML tools have become "good enough" (still wish Notion had PlantUML support instead of mermaid...), but I'm incredible thankful your service is still up and running.
I like Mermaid fine, but nothing is perfect. I will look at your list. The tool I always wanted would let me paste in the SQL of my database schema and output a diagram of the tables and relationships. That's SQL and not Markdown or JSON or any other format.
Note that DrawDB (www.drawdb.app) does this, although it does not yet handle views. But I have been happy with what it offers so far. Still, I would welcome suggestions of other tools.
This is based on graphviz, and with the available layout algorithms, any schema with more than 5 tables and a few foreign key relation becomes a jumbled, unreadable mess.
Since you asked for recommendations: Cacoo (https://nulab.com/cacoo/) has this function. You input your database schema SQL and it generates an editable diagram with all the relationships.
Disclaimer: I work for them. I’m the person who developed that feature.
I was wondering, are there any tools that could help to draw decent looking genealogical tree ? My main issue are the updates, where adding one of the ancestors or newborns causes full rework of entire tree. I'd like to feed data to some script and have it render a family tree, with all the regular updates.
https://www.familyecho.com/ is the lightest one. It's almost offline. Some light reverse engineering can make it work totally offline. I saw a version of it on Github too. Some features had problems, I think it was printing which was failing.
The main benefit for me to just know and primarily use mermaid is that it integrates with markdown in Azure DevOps and GitHub seamlessly. No need for a text to image build step or similar.
They might be "better", but Mermaid works offline (there's a cli) which makes it a much better choice, along with PlantUML. An online tool might be good for making one off things you know you won't ever need to change, but my main use case for these tools is documentation which, naturally, needs to change over time.
I think almost all of the tools I listed are offline. They do load in browser, but from there they don't use server to render diagrams. Some aggregator tools like Kroki is of course not offline though.
You're catching more heck than me but, for real it's a great competitive cross cut. Maybe my remarks seemed flippant but, curated list like this is what I wish Google or AI could deliver. It's quality content.
IMO mermaid is awesome, but for two somewhat indirect reasons:
- There’s an almost wysiwig editor for mermaid at https://www.mermaidchart.com/play . It’s very convenient and appropriately changes the layout as you draw arrows!
- Notion supports inline mermaid charts in code blocks (with preview!) It’s awesome for putting some architecture diagrams in Eng docs.
Obsidian also supports inline mermaid charts in markdown code blocks. One of those features I don't see mentioned much.
LLMs (I use ChatGPT) can take a generic process description, spit out the result in mermaid, which can then be imported and refined in something like draw.io. Yes, you’ll have to correct a few things by hand, but it drastically speeds things up. Last time I check draw.io is supported in obsidian.
github / gitlab too!
Supernotes too!
Github supports inline mermaid charts, too!
I've been starting to include them in my bigger PRs and reviewers really like them.
About Notion, they do indeed support Mermaid, but their included version is quite obsolete and they don’t seems so eager to update it. A shame.
Hugo does this as well.
One of my favorite applications of multimodal LLMs thus far is the ability to:
1. Draw a DAG of whatever pipeline I’m working on with pen and paper.
2. Take a photo of the graph, mistakes and all.
3. Ask ChatGPT to translate the image into mermaid.js
Given how complicated the pipelines are that I’m working with and the sloppiness of the hand drawn image, it’s truly amazing how well this workflow works.
I recently did a variation of this where instead of drawing, I just drafted a quick few bullet points and text describing at a high level what the system should do. And then I asked chat GPT to identify use cases and generate sequence diagrams for each use case in puml format (plantuml). Shockingly effective and it took about five minutes. This was a technical proposal that I shared with a few partner companies to provide a detailed plan to a customer. It came after several online meetings spaced over a few weeks of us negotiating the details. Pretty important document and it was well received. Plantuml looks decent enough that you can get away with sticking the resulting diagrams in a document.
I'm a busy person. I don't have hours of time that I can take out of my schedule to generate what I regard as write only documentation (nobody will ever read or truly value it) that ticks the box of "we have stuff to point at when somebody asks (which nobody ever will)", which has a lowish value. Sometimes it's nice to have. The above is a fine example. People will glance at it, give me a little thumbs up, and then give me permission to proceed as planned and bill accordingly. Job done. It's not a reference design that anyone will ever look at for more than a few seconds.
After a few decades in the industry, I'm extremely skeptical of the value of diagrams vs. the time required to produce them. I just don't see it. A lot of good software gets produced without them. You don't need blueprints for your blueprints, which is what source code is (a blueprint for automatically compiling into working software). People value such traits as structure, readability, conciseness in source code for a reason: it allows them to treat source code as design assets. I don't write UML, I stub out data classes and interfaces instead. And then I refactor them over and over again. Diagrams just slow me down.
But a few minutes is about on the threshold of me wasting braincycles on producing them and enrich documentation that I'm writing anyway in text form. Quickly jot down some notes. Don't waste any time whatsoever obsessing about the awkward syntax of these micro languages, and just get the essentials nailed. I bet I can get it down to like a minute or so with better LLMs and larger context windows. "Examine this project, produce an overview diagram of all the database tables". That's a prompt I'd write. In the same way, letting LLMs document code is a great use of time.
> write only documentation (nobody will ever read or truly value it)
But what's the point of producing such documentation? I could imagine that the process of creating it could be somehow beneficial (committing to memory, finding discrepancies, etc). If it's not, why can't it just be skipped?
Documentation is a tool for creating shared understanding. If you don’t need to share your understanding, don’t write docs.
Note however that sharing understanding works on the people axis and on the time axis. Docs allow you to share your current understanding with your future self. They’d better be general enough to be true then, though.
Nowadays I find Gemini pro to be able to accurately document a complex workflow within minutes just by looking at the sources and sometimes even just logs, so value of low level docs is questionable. High level requirements - essentially how it’s supposed to work and what for - is very valuable, as it allows you and the model to cross check whether things work as they were intended.
I write and read lots of documentation. Diagrams are not a common feature of that.
I'd rather have a single concept diagram than a thousand words of docs. To each their own I guess.
None other than ticking boxes and shutting up the people that keep asking for such things to be produced. Who then invariably don't have the attention span to do anything with the diagram. That's literally the only reason I have for creating them. Otherwise it's a tedious activity that gets in the way of developing, slows me down, and just interrupts my creative process. I usually have better things to do.
And as you might understand from what I just said, I rarely produce any diagrams. I've been active as a developer since before UML got popular and then peaked and then faded into obscurity. I still have a signed (by Martin Fowler) copy of UML distilled on a shelf somewhere gathering dust. First edition and everything. I don't think it's very valuable. Waste paper basically. But contact me if you feel otherwise. It's in pristine condition because I never did much more than thumb though it and shelve it.
25 years ago, any self respecting architect had expensive licenses for things like rational rose or visio. And they'd be fiddling with those tools for hours to produce detailed class and other diagrams. And those diagrams were as useless then as they are now. Epic waste of time. People stopped buying and using those tools. This was once a very big industry that has now imploded to next to nothing. Nobody is buying, very few people waste budget on this crap. It's a niche market with some niche revenue. Tens of millions of developers ignore these tools.
What do plantuml, mermaid, and other OSS diagramming tools have in common? The people that make them don't eat their own dogfood to document how their own software works. You can have some fun looking for diagrams in OSS projects. With few exceptions, this is not a thing (devops people seem to have a weird obsession with diagramming. And overengineering). I'm not aware of many serious OSS project where developers have bothered to document even a tiny fraction of their software with diagrams. Including all the major OSS UML diagramming tools.
The documentation for these contains plenty of examples of course (typically very simplistic). Just not any that document how the tool is designed or works. I'm not judging. I wouldn't bother either for reasons that I articulated above. But I find it ironic that even diagram tool developers don't seem to feel an urge to use diagrams for their own stuff. Makes you wonder why they bother creating the tool? You'd have to be passionate about diagramming tools but not so that you'd want to use them for your own software.
The answer is literally in the same sentence you quoted…
Care to share your prompt(s)?
I draw a fair bit on a Kindle Scribe. I’d love to try this, but I bet your prompt would be helpful.
There's really not much to share. I rewrite the prompt each time, but here's was a recent one:
> I have an image of a hand drawn workflow diagram. I’d like to turn it into a mermaid.js file.
(with the image attached)
Alternatively, ask the LLM to create a mermaid DAG of your current code.
That's an interesting idea. A lot of times what I'm drawing is a blend of what the code is versus what I want it to be post-refactor.
I just used Mermaid for multiple sequence diagrams from build-steps sequences in a video talk I did on comparing build systems - https://www.youtube.com/watch?v=L67ri_xe2oQ (slides - https://paulhammant.com/google-style-dag-build-systems/). The new boost for me was GPT4o. It was able to quickly make what I wanted from the build logs alone, though it took some hand tweaking too. A new (or very old) problem after that was not taking sufficient save points (URL bookmarks) and sometimes making the same edit twice cos I'd lost a URL. That there was a second save of the PNG form for each (https://kroki.io/mermaid/svg/...) added to the keep-track-of-changes problem for me, especially when I'm very tired me :(
Interesting slides, it's always nice to see different ways to set up these kinds of systems and with a practical git repo to boot!
Check out Kroki for a multi-syntax wrapper around a bunch of text driven diagram generators —- including Mermaid, PlantUML, Ditaa, GraphViz, SVGBob, etc, etc
https://kroki.io/
That's pretty slick, thanks for sharing. https://github.com/yuzutech/kroki (MIT) and they thankfully use Zulip for their chat!
I'm slightly surprised excalidraw (https://excalidraw.com/) is not in the comments. I use it regularly to convey ideas to my devs and designers. Plus, it exports to json! Someone wrote a library to convert mermaid to excalidraw as well.
We're now experimenting with creating design questions to ask in interviews with excalidraw/mermaid
I love excalidraw. But does it have an editable, diffable textual representation? Can it be generated with little ceremony, and laid out automatically?
The sibling submission about https://kroki.io has an Excalidraw in https://kroki.io/#examples and the input is the following, so presumably "yes" and "no"
Yes, textual, but no, the diffs aren't going to mean anything. It'll be like diffing svg from InkscapeI did a system design interview awhile back using Excalidraw. I really enjoyed it (though I also frequently use it for normal work stuff, so was familiar with it).
I much prefer d2 https://d2lang.com/
Only downside is AFAIK no in-browser renderer.
The other downside is that D2 is a thinly-veiled Open Core project and you'll be forever stuck with yet another company trying to get money from you:
https://d2lang.com/tour/tala/
> Proprietary layout engine developed by Terrastruct
> TALA is a separate install from D2, to keep a clean cut between 100% free and open-source D2, and proprietary, closed-source TALA.
The two non-proprietary layout engines are 1) Dagre, a port of ideas from Graphviz to Javascript, where the only benefit over Graphviz seems to be "it's in Javascript!" 2) ELK, a fairly naive layout engine that makes non-symmetrical graphs with oddly crooked lines.
It's weird to me that TALA is considered the "special sauce" layout engine, because I've only ever had it produce extremely weird layouts for me.
I always tend to end up using ELK.
That’s a pretty major downside, since broad in-browser support (GitHub, Notion etc) is arguably Mermaid‘s USP.
It's not too bad if you're prepared to set up a rendering pipeline using a static site generator like mkdocs. This will get you much better results than just letting GitHub et al render markdown in whatever style they please.
We're quite happy with mermaid though, not sure what's the issue with it?
Well it just can't do as much as many other tools.
They were working on a wasm version some time ago I believe [0]. Not sure how usable this is insofar, but it may be of interest.
[0]: https://github.com/terrastruct/d2/pull/436/files
https://play.d2lang.com/ loads https://play.d2lang.com/d2.wasm so presumably "all done"
I don't love Mermaid and generally find it less well designed than something like Graphviz/dot. I generally find a lot of the syntax needlessly strict for something non-programmer humans are meant to interact with, but the big seller for me with Mermaid is that it works inline on GitHub.
I end up creating a lot of sequence diagrams and having them as editable mermaid is very convenient. I do wish GitHub giant mermaid navigation controls floating over the bottom right corner obscuring things.
I was under the impression mermaid is a wrapper around graphviz dot.
No, it's an independent, JS-only implementation, and it's way, way less featureful.
I believe it uses an cross compiled version of dot in js
I don't see the infrastructure for that, rather it seems to be relying on d3 and DAG renderers targeting it https://github.com/mermaid-js/mermaid/blob/mermaid%4011.6.0/...
I use Mermaid in my app[0] to generate books story relationships.
[0]https://github.com/herol3oy/austen
Your app looks interesting. Am curious about how is AI being used. Assuming that to discover character relationships, how is that done? Thanks.
Little weird to see this on the lead page… mermaid has been around for a long time. And in general I’ve found its real world use pretty lacking.
I use it and see it many times per month as it’s the preferred way of sticking graphics and diagrams in markdown in git repos and generated static sites.
It’s so handy for putting a sequence diagram in your docs and then tracking the changes over time using git.
I’m curious what other software developers use if not this. I’ve tried specific graph and drawing tools like lucid and Visio, but the simplicity of mermaid is nice. And I don’t know anything else that shows git blame for who changed what in my diagram, when.
Re what other developers use. I tried mermaid and other text to diagram tools for work, but, as mentioned above, found them lacking. Most companies / teams I know of use something like excalidraw or miro. Definitely matches your simplicity requirements, but, obviously, no git blame
I haven’t tried excalidraw, but don’t like miro as I want my docs embedded with the repo, not linking out to a third party.
I like miro for brainstorming and such.
> And I don’t know anything else that shows git blame for who changed what in my diagram, when.
You could do this with any diagrams-as-code tool, no?
Mermaid is sort of a defacto standard because github auto renders it inside markdown files.
I think he's saying you can click and edit on the diagram, which mermaid doesn't support. This does propagate back into the source.
I think you are talking about "just change the text and regenerate", which achieves much the same goal.
I'm not sure in what cases the former is better.
Such as?
I love it when this happens, people almost always reply with something cool they did with it, or discovered. The link isn't new, often the comments are.
Its real-world use is drawing diagrams on a web page! I much prefer diagram-as-code to diagram-as-screenshot. e.g. https://sbs.johnnydecimal.com/14.23+OPS1#diagram
We use it a lot for internal documentation, eg in Markdown on GitHub (renders natively), Notion, and Jira.
I love Mermaid diagrams. I let my coding LLMs generate diagrams during architecture design and then afterward for accuracy— Sequence Diagrams, CSD’s, Flowcharts, DFDs, and ERDs. Couldn’t be simpler. I’m happy.
Yes, I think this is why mermaid is hard to beat right now. LLMs seem to understand the syntax well.
I’ve used AI to build mermaid diagrams during ongoing system design discussions from transcripts as they progress.
I’ve rendered them, shared them and then the group can look at them and iterate very quickly.
A bunch of the rendering tools aren’t great, but some are and decent basic styling makes a big difference.
This is built into Obsidian, and I love it for making quick diagrams in my notes.
Mapping out database tables while I’m conceptualizing an idea is what I use it more most often. I also use sequence diagrams to map process flow or try e flow of information.
I remember I use this last year when trying to draw my auth flow. I tried using excalidraw but it gets laggy if your chart is too big, besides I find it easier to type the chart than using the mouse.
Like PlantUML?
Nicer looking but fewer diagram types
Also, AFAIK, their "render locally" story is "boot up headless chrome, good luck" which isn't great
Picking anything but PlantUML's default theme will make PlantUML look less 90's-Java. As a minimalistic solution, I already like "skinparam monochrome true" https://plantuml.com/skinparam#:~:text=Black%20and%20White. (You can go further with CSS and themes and...)
There are plugins for VS Code that enable local rendering when previewing markdown files. Fairly nice for editing dev wiki files!
Another comment mentioned along the lines of, "it's the goto used by developers in readmes", and I suspect it's more specifically javascript-adjacent developers (as is the case where I work)
The "render locally" situation was enough friction to keep me happy with my .jpgs and .pngs generated from various sources and/or screenshotting.
I don't know if this helps you but the Mermaid plugin in JetBrains has an export feature which can save you a step. But I find Mermaid diagrams so limiting and the syntax more immature than PlantUML so it's very rare that I bother
The "in readmes" is a special case because the markdown rendering in both GitHub and GitLab support it without drama
Except it has trouble rendering text on the CLI version when producing SVGs.
i have been quite enjoying https://www.eraser.io/diagramgpt
All I really want is something that can diagram out 30+ microservices and interconnections without getting ugly.
graphviz does okay, but I kinda want some extra levels of grouping to keep services in the same k8s namespace close together.
Are clusters not enough?
They can be nested.
https://graphviz.org/Gallery/directed/cluster.html
https://github.com/ReneNyffenegger/about-Graphviz/blob/maste...
Hmm. I thought I'd tried that but perhaps I didnt' read the documentation close enough. Even after reading your reply it took me about 20 minutes to realize the subgraph has to have a name prefix of "cluster." And after more digging I see now that cluster=true will do it as well.
It's not exactly what I was hoping for, but is an improvement on the randomization I had going on before!
I liked Mermaid but unfortunately LLMs don't understand it well, so I switched to Latex tikz which LLMs know pretty well. At least I know Gemini 2.5 Pro does a good job at tikz. 3.7 and o1 were meh.
deepseek r1 understands mermaid very well and can correct all the mistakes of Gemini and Claude
I can second this. I’ve been using R1 to both straight up generate mermaid as well as making custom mermaid syntax generators for dynamic diagramming
Claude Artifacts will generate mermaid diagrams for you.
On my RooCode chat window with Gemini2.5 the mermaid charts are not always shown... 44049619.
I have an almost exhaustive list [1] of browser based text to diagram tools. Some specialised tools (like https://sequencediagram.org/) so much better at what they do than any generic ones like mermaid.
[1] https://xosh.org/text-to-diagram/
I wish WebSequenceDiagrams was further up your list. I guess I have some work to do.
When I made it, nothing like mermaid, plantUML，lucid charts existed. The syntax of most tools was based on Java or graphviz and overly verbose. I was writing an email to a colleague at BlackBerry and wrote out the sequence diagrams as text. I spent the next week making a script to convert it to an image and put it online. Many other tools have since adopted the syntax and I'm happy it has become so widespread.
Great tech - thanks for your pioneering work. I made https://vsm-book.com/app as a tool to support a meeting and leave a lasting artifact. WebSequenceDiagrams (and https://bramp.github.io/js-sequence-diagrams/ which also credits yours) was very much in my mind, though my grammer is much less elegant.
Thank you so much for WSD.. I've used it extensively for at least a decade. We even self hosted it at one place after I pushed for it.
It was indeed pioneering in its day, though I find the default mermaid integration in the likes of Notion make it the (generic) goto for the team now.
Thank you so much for your work!
WebSequenceDiagrams has been my go to for years, and I'd be basically brainstorming straight in it in lieu of pen and paper. I laughed the day one of my colleague was explaining his issue on the whiteboard and he was writing it "A->B: some action" style instead of the actual box and arrow sequence, it just became part of our culture I think.
I had to move on when I couldn't get it approved at the place I worked, and nowadays PlantUML tools have become "good enough" (still wish Notion had PlantUML support instead of mermaid...), but I'm incredible thankful your service is still up and running.
I like Mermaid fine, but nothing is perfect. I will look at your list. The tool I always wanted would let me paste in the SQL of my database schema and output a diagram of the tables and relationships. That's SQL and not Markdown or JSON or any other format.
Note that DrawDB (www.drawdb.app) does this, although it does not yet handle views. But I have been happy with what it offers so far. Still, I would welcome suggestions of other tools.
Check out dbdiagram.io though I don’t know if it handles views either, I never tried.
If it's sqlite compatible, then there a many solutions. In general it's trickier.
plug: https://github.com/dgoffredo/sqliteviz
Not web based, though.
This is based on graphviz, and with the available layout algorithms, any schema with more than 5 tables and a few foreign key relation becomes a jumbled, unreadable mess.
Here's one with 16 tables: <https://raw.githubusercontent.com/dgoffredo/sqliteviz/refs/h...>.
Not the prettiest, but workable.
I wouldn't try it on 100 tables.
Since you asked for recommendations: Cacoo (https://nulab.com/cacoo/) has this function. You input your database schema SQL and it generates an editable diagram with all the relationships.
Disclaimer: I work for them. I’m the person who developed that feature.
Feedback welcome!
I was wondering, are there any tools that could help to draw decent looking genealogical tree ? My main issue are the updates, where adding one of the ancestors or newborns causes full rework of entire tree. I'd like to feed data to some script and have it render a family tree, with all the regular updates.
https://www.familyecho.com/ is the lightest one. It's almost offline. Some light reverse engineering can make it work totally offline. I saw a version of it on Github too. Some features had problems, I think it was printing which was failing.
That's an amazing list! If you're writing in asciidoc like I generally do, here's the subset that you can write directly in your document: https://docs.asciidoctor.org/diagram-extension/latest/
The main benefit for me to just know and primarily use mermaid is that it integrates with markdown in Azure DevOps and GitHub seamlessly. No need for a text to image build step or similar.
Same reason. I can add to this list Readme.com and Notion.
This is a great resource. Thank you for the effort. Do you know of something similar for charting/data-viz libraries?
Nice list, thanks for compiling it. It looks like you have "textik" in there twice in positions 11 and 13.
They might be "better", but Mermaid works offline (there's a cli) which makes it a much better choice, along with PlantUML. An online tool might be good for making one off things you know you won't ever need to change, but my main use case for these tools is documentation which, naturally, needs to change over time.
I think almost all of the tools I listed are offline. They do load in browser, but from there they don't use server to render diagrams. Some aggregator tools like Kroki is of course not offline though.
Thank you, that's handy!
But they are browser based.
Yes. Most of them are offline even if they load in browser. Diagram is rendered right inside the browser.
This list is so cool!
70! That is awesome
70!? That’s more than a Googol!
You're catching more heck than me but, for real it's a great competitive cross cut. Maybe my remarks seemed flippant but, curated list like this is what I wish Google or AI could deliver. It's quality content.
[dead]