I really like Mermaid, but I'm not seeing the value in this as is.
- Mermaid within .md is widely supported. The file format of .mmd, while supported in most integrations, is a standalone file rather than living within my documentation/markdown. I use Mermaid charts and graphs as visual aids to add to the documentation or notes rather than having them stand alone. If I wanted a standalone file, I'd use any other diagram tool with its proprietary file format. I like Meriamid because of how easy it is to integrate into markdown. The value isn't in having a Mermaid file; the value is in adding diagrams and charts to markdown.
- Within .md files there's a Mermaid logo added beside the Mermaid, but it doesn't seem to be clickable or have a context menu. Maybe this is a bug. It also weirdly highlights all of the Mermaid code. Why doesn't it syntax highlight within markdown? This extension works great for highlighting: https://marketplace.visualstudio.com/items/?itemName=bpruitt...
Just to draw more attention to the point, it's not an unrelated project simply "using the Mermaid name," it's a for profit project started by the creator of mermaid.js, which charges for some advanced tooling around the opens source project. It's a common enough paradigm to see and in my opinion a pretty virtuous way to fund open source development.
It's pretty instinctive to name stuff like this, especially when it's not a general purpose solution like you're not downloading this for any other reason except to build upon what Mermaid does.
They could have called it something entirely different, and then they can say (vscode plugin for mermaid.js) every time they mention their unique name that carries no association with it.
And Mermaid could have decided they want exclusive use of the name and trademarked it half a decade ago.
The problem is that a lot of people will google mermaid chart, or come across an extension like this, and find a site that looks like the official website and docs but isn't; it's a paid product with no relation that's simply profiting off of the name. That's deceptive, regardless of whether it's "fair use" or not.
Honestly, I'm surprised anyone on HN would defend that sort of behavior.
Hi, I wanted to add some clarification on this topic.
I am Knut Sveidqvist, the inventor of Mermaid and creator of the Mermaid open-source project. I'm also the co-founder of Mermaid Chart.
To address the confusion: Mermaid Chart is not a separate entity "profiting off the name" - it's a commercial offering I created to help sustain the open-source project. Working on Mermaid during evenings and weekends became unsustainable as the project grew. Mermaid Chart allows me to work on what I love full-time while providing resources back to the open-source project. This support will continue to grow as our business matures.
I appreciate your concern about protecting users from deceptive practices. In this case, there is a direct connection between the open-source project and the commercial offering, created by the same founding team.
Thanks for the clarification! Glad you can cater to both worlds.
For diagramming and even UI prototyping I keep getting back to plain old ascii drawings though. Asciiflow.com is fantastic. I just wish they had vim keybindings. It's also great to embed in .md too. Could mermaid generate ascii? It just seems easier to comprehend and doesn't need a separate renderer.
No it can not. That's an interesting idea, though, but one would need to navigate/differentiate between the rendered output text and the Mermaid diagram code.
Mermaid.js.org links directly to Mermaid Chart, and there is a blurb on the org site that says, "Mermaid + Mermaid Chart... Mermaid Chart is a major supporter of the Mermaid project."
Well, at least they're supporting the project and they're ok with it.
It's not uncommon for companies to piggyback off an open source project's success and mislead people into thinking it's theirs. Seemed an awful lot like that was the case here.
This. On the Mermaid Chart site they say:
"By the creators of Mermaid JS"
I don't know the details but assuming they're being truthful, there definitely appears to be a tight relationship.
> And Mermaid could have decided they want exclusive use of the name and trademarked it half a decade ago.
If you do not trademark your name then I can only assume you do not want exclusive control of that name - I certainly wouldn't assume you want the protections a trademark grants.
"You didn't register your trademark, so I guess you don't care if I use it!" Setting aside mermaid here, that line of thinking is not only legally precarious but heavily unethical. In the US at least, trademarks are implicit, like copyright. Registering a trademark can help in court, but it's not required.
I'll cede it might be precarious but the whole point of having trademark protections you apply for is by definition contingent on not having those protections if you don't apply for them. If you don't apply for them and someone else uses the name too why should you care?
To me it sounds like when open source project resenting a very-permissive license just after someone else turns it into a profit machine. Kind of sucks but also the whole point of that permissive license is you shouldn't care.
> Honestly, I'm surprised anyone on HN would defend that sort of behavior.
Saying "that's legal; if they didn't want it to happen they'd have trademarked" is the correct response. We can socially shame a behaviour on a random comment section on the internet, or we can actually provide the solution to all future people: trademark it if you want it.
Love mermaid. And for me mermaidchart.com was synonymous with mermaid markup. Thank you very much! I didn’t know the official website of the project is https://mermaid.js.org/ Just learned from you.
Perhaps PlantUML isn't as new and interesting as Mermaid, but each time I try a side-by-side comparison, the results are always better in PlantUML than Mermaid. I'll admit that the Mermaid syntax is a lot easier to understand, but the PlantUML syntax is a lot more powerful. I especially like the new Activity diagrams in PlantUML with the conditionals and looping syntax.
I use it mostly for sequence diagrams, but never hit a case where Mermaid felt better than PlantUML. It has been more of a forced transition as SaaS like Notion don't have a PlantUML integration or it's not available at the organization level.
Mermaid is fantastic as a portable I/O format for LLM context. I spent some time discussing entity relationships with an LLM recently, and had it produce a Mermaid diagram to wrap up the conversation.
Once you have the diagram code, you can use that as an artifact for new LLM chats related to databases, APIs, etc.
I'm not sure what the history of mermaidchart.com specifically is, but I'm guessing it's new since the ER diagram docs are marked as "coming soon":
It is. I had a meeting this past week where we discussed a novel workflow and I was able to generate an initial based on the transcription of our discussion so far, then two quick revisions based on realtime feedback.
Though, I’ve used it to generate visuals of pipelines too and find it often takes coaching similar to any output that requires very high precision.
Another bit is that gpt4o and sonnet both seem to want to put syntax breaking parentheses in and struggle to avoid continuing to do so.
Once it’s right, though it is a valuable new context artifact to include in further problem solving on a domain.
Is there anybody creating Mermaid diagrams with LLMs, especially? I tried with Claude and R1 (ProxyAI plugin for Jetbrains) and I had to find the correct phrasing to interact with it. Does the Mermaid-blessed AI have any secret sauce or can I instruct any LLM?
Re: LLMs & diagrams - in general, diagrams and tables as info compression tool (both in the general sense as well as in the practical concrete "optimise for token / context window" sense) - e.g. today as part of request to do 'deep research' on Dwarf Fortress personality / psychology system, at a late point (preparing to relaunch with a fresh empty context window among other things) I asked GPT 4.5 to (among other diagrams) draw me a concise 'psychological data flow diagram' (I was kind of vague and was deliberately pushing for abstraction / compression) -
among (many elaborate) other things it gave me - and I liked it (NB don't trust it willy nilly w.r.t. the below of course) - (auto-indented by 2 spaces hope formatting works) =>
p.s. it chose the syntax/format itself; regardless, some time ago when asked for guidance re: how to manage sliding context window, it did suggest tables itself (user employing them for concise input - and likewise requesting tabulated/diagrammatic/schematic output).
p.p.s. (edit) many good very particular insights, if anyone's by chance interested then lmk, I'll ping once distilled interesting output is on a not-yet-extant blog (it's gonna happen finally)...
Don't mean to be blunt, but I found your comments really hard to comprehend. Something about the phrases feels atypical, almost like it's a different dialect. Curious if it's just me.
Never seen a bigger waste of time than when my colleague (who was given more authority for some reason) tried establishing Mermaid as our go-to diagramming tool for the company.
Had no real benefits, was way more cumbersome for almost everyone and honestly even me as a developer I'd rather have a few paragraphs instead of a diagram.
I find that tools like Mermaid are pretty invaluable, especially when editing very large processes. Draw.io diagrams tend to get pretty unwieldy as they scale and editing inter process stuff if you forgot something quite frustrating.
Admittedly I primarily use D2 nowadays. The only features I miss in D2 from mermaid are the GitHub automatic rendering and Sequence diagram numbers. https://play.d2lang.com
I use excalidraw, even upgraded to pro out of my own pocket. It's not git-compatible in the sense that it's not text (though you can export to SVG and commit that, which I've done). But I love that it has the feel of an approximation or just a quick sketch rather than a formal promise of how a system works.
When I've used dot or mermaid to build diagrams I've always found it hard to specify layout, colours and sizes, which I use to emphasise different views on a system. I'd love some sort of middle ground where I get the benefits of version control but also the sketch-like character of excalidraw
I'm actually not sure, It's no really a flowchart editor, more of a vector drawing program, though it has some features like being able to pin the end of a line to an object so it follows while you drag
From the post: All diagrams that look like the top image or the mermaid example after the complex one, could just be a list of steps.
For the complex one, maybe yes, it makes sense to have an overview and I think maintaining that vs text is also easier. However from what I've seen, most things can be boiled down to a list of 1, 2, 2.1, etc.
Nowadays I use mermaid, but I only use sequence diagrams. They're incredibly useful to convey to a client at a high-level what are the different workflows in a system.
My colleagues frequently use one of these general-purpose WYSIWYG drawing tools, and I'm not a fan at all – everybody has their own slightly or wildly varying riff on UML or flowcharts, and the result is chaos: Sometimes rectangles are states, sometimes they're decisions; sometimes arrows are labeled state transitions, but other times they're unlabeled and state transitions are also boxes.
Discoverability is also much worse compared to e.g. Mermaid or PlantUML diagrams checked into version control or stored as text source in Wiki articles.
I also ran into massive issues trying to use Mermaid when I tried to pair it up with Marp (markdown for presentations). I am not sure if it is Mermaid's fault or Marp's fault but it didn't work and tons of people want it to work:
Commented elsewhere, sorry should have clarified. Just a bit of text, mostly a bit of context of the requirements, potential edge cases and then an ordered list of steps
I have been using mermaid with gpt... describing the diagram I want and getting the syntax, then copy pasting it into the repl. I also wanted to investigate using marp for quickly coding up power point slides. But I regularly ran into issues with customising styles and documentation around html so I gave up on that
I can blast out auto-reflowing flowcharts in Flying Logic on a keyboard but it's moved to a subscription model that doesn't make sense for my irregular use.
Seeing the connections in real time really helps with my thought process.
Using the extension, you can see your changes from the Mermaid Code rendered as a diagram in real-time.
If you also want to interact with the diagram itself to make the changes, you can do that using the Mermaid Chart Playground: https://www.mermaidchart.com/play
Now, we have added lots of new functionality. Proper editing with syntax highlighting, etc. Apart from that, we have also added integration with GitHub Copilot, so you can generate diagrams from code and continue to edit them using the extension.
I have been using it lightly. But the biggest problem (for me) is that I cannot use custom icons. I have to use Azure specific icons in a lot of diagrams. Mermaid's support for custom icons is only via iconify packs as far as I can tell. Is it possible to refer to icons in a local directory, such as "./images/storage.png"?
Does this let you export rendered diagrams at html or pdf?
The Markdown Preview Enhanced plug-in is the only plugin I found to do this easily lady time I was looking .
I really like Mermaid, but I'm not seeing the value in this as is.
- Mermaid within .md is widely supported. The file format of .mmd, while supported in most integrations, is a standalone file rather than living within my documentation/markdown. I use Mermaid charts and graphs as visual aids to add to the documentation or notes rather than having them stand alone. If I wanted a standalone file, I'd use any other diagram tool with its proprietary file format. I like Meriamid because of how easy it is to integrate into markdown. The value isn't in having a Mermaid file; the value is in adding diagrams and charts to markdown.
- Within .md files there's a Mermaid logo added beside the Mermaid, but it doesn't seem to be clickable or have a context menu. Maybe this is a bug. It also weirdly highlights all of the Mermaid code. Why doesn't it syntax highlight within markdown? This extension works great for highlighting: https://marketplace.visualstudio.com/items/?itemName=bpruitt...
- It doesn't add support for viewing mermaid within markdown preview. I currently use this extension for it. This is a key feature that is missing. https://marketplace.visualstudio.com/items/?itemName=bierner...
Overall, excited to see what this becomes. Hope this is useful feedback! It can only get better from here.
It's worth pointing out that mermaidchart.com is NOT the official Mermaid project (https://mermaid.js.org/).
They're a for-profit company using the Mermaid name.
This creates a lot of confusion whenever the name comes up, which I suspect is deliberate.
Just to draw more attention to the point, it's not an unrelated project simply "using the Mermaid name," it's a for profit project started by the creator of mermaid.js, which charges for some advanced tooling around the opens source project. It's a common enough paradigm to see and in my opinion a pretty virtuous way to fund open source development.
See also Redis labs, Gitlab, ElasticSearch...
It's pretty instinctive to name stuff like this, especially when it's not a general purpose solution like you're not downloading this for any other reason except to build upon what Mermaid does.
They could have called it something entirely different, and then they can say (vscode plugin for mermaid.js) every time they mention their unique name that carries no association with it.
And Mermaid could have decided they want exclusive use of the name and trademarked it half a decade ago.
So it's just fair use, isn't it?
The problem is that a lot of people will google mermaid chart, or come across an extension like this, and find a site that looks like the official website and docs but isn't; it's a paid product with no relation that's simply profiting off of the name. That's deceptive, regardless of whether it's "fair use" or not.
Honestly, I'm surprised anyone on HN would defend that sort of behavior.
Hi, I wanted to add some clarification on this topic.
I am Knut Sveidqvist, the inventor of Mermaid and creator of the Mermaid open-source project. I'm also the co-founder of Mermaid Chart.
To address the confusion: Mermaid Chart is not a separate entity "profiting off the name" - it's a commercial offering I created to help sustain the open-source project. Working on Mermaid during evenings and weekends became unsustainable as the project grew. Mermaid Chart allows me to work on what I love full-time while providing resources back to the open-source project. This support will continue to grow as our business matures.
I appreciate your concern about protecting users from deceptive practices. In this case, there is a direct connection between the open-source project and the commercial offering, created by the same founding team.
Thanks for the clarification! Glad you can cater to both worlds.
For diagramming and even UI prototyping I keep getting back to plain old ascii drawings though. Asciiflow.com is fantastic. I just wish they had vim keybindings. It's also great to embed in .md too. Could mermaid generate ascii? It just seems easier to comprehend and doesn't need a separate renderer.
No it can not. That's an interesting idea, though, but one would need to navigate/differentiate between the rendered output text and the Mermaid diagram code.
Mermaid.js.org links directly to Mermaid Chart, and there is a blurb on the org site that says, "Mermaid + Mermaid Chart... Mermaid Chart is a major supporter of the Mermaid project."
Well, at least they're supporting the project and they're ok with it.
It's not uncommon for companies to piggyback off an open source project's success and mislead people into thinking it's theirs. Seemed an awful lot like that was the case here.
This. On the Mermaid Chart site they say: "By the creators of Mermaid JS" I don't know the details but assuming they're being truthful, there definitely appears to be a tight relationship.
> And Mermaid could have decided they want exclusive use of the name and trademarked it half a decade ago.
If you do not trademark your name then I can only assume you do not want exclusive control of that name - I certainly wouldn't assume you want the protections a trademark grants.
"You didn't register your trademark, so I guess you don't care if I use it!" Setting aside mermaid here, that line of thinking is not only legally precarious but heavily unethical. In the US at least, trademarks are implicit, like copyright. Registering a trademark can help in court, but it's not required.
I'll cede it might be precarious but the whole point of having trademark protections you apply for is by definition contingent on not having those protections if you don't apply for them. If you don't apply for them and someone else uses the name too why should you care?
To me it sounds like when open source project resenting a very-permissive license just after someone else turns it into a profit machine. Kind of sucks but also the whole point of that permissive license is you shouldn't care.
> Honestly, I'm surprised anyone on HN would defend that sort of behavior.
Saying "that's legal; if they didn't want it to happen they'd have trademarked" is the correct response. We can socially shame a behaviour on a random comment section on the internet, or we can actually provide the solution to all future people: trademark it if you want it.
Love mermaid. And for me mermaidchart.com was synonymous with mermaid markup. Thank you very much! I didn’t know the official website of the project is https://mermaid.js.org/ Just learned from you.
They even have almost identical logos...
Mermaid Charts is the company run by Knut Sveidqvist, the original author of Mermaid [1]. I don't think it's disingenuous at all.
[1] https://www.mermaidchart.com/company
Perhaps PlantUML isn't as new and interesting as Mermaid, but each time I try a side-by-side comparison, the results are always better in PlantUML than Mermaid. I'll admit that the Mermaid syntax is a lot easier to understand, but the PlantUML syntax is a lot more powerful. I especially like the new Activity diagrams in PlantUML with the conditionals and looping syntax.
Thats what I also found out, supported by llms, nice looking output. I have not found a proper left to right renderer for the activity diagrams
Agreed.
I use it mostly for sequence diagrams, but never hit a case where Mermaid felt better than PlantUML. It has been more of a forced transition as SaaS like Notion don't have a PlantUML integration or it's not available at the organization level.
Mermaid is fantastic as a portable I/O format for LLM context. I spent some time discussing entity relationships with an LLM recently, and had it produce a Mermaid diagram to wrap up the conversation.
Once you have the diagram code, you can use that as an artifact for new LLM chats related to databases, APIs, etc.
I'm not sure what the history of mermaidchart.com specifically is, but I'm guessing it's new since the ER diagram docs are marked as "coming soon":
https://docs.mermaidchart.com/mermaid/er/syntax
I'm curious how this plugin compares to Markdown Preview Mermaid Support: https://marketplace.cursorapi.com/items?itemName=bierner.mar...
It is. I had a meeting this past week where we discussed a novel workflow and I was able to generate an initial based on the transcription of our discussion so far, then two quick revisions based on realtime feedback.
Though, I’ve used it to generate visuals of pipelines too and find it often takes coaching similar to any output that requires very high precision.
Another bit is that gpt4o and sonnet both seem to want to put syntax breaking parentheses in and struggle to avoid continuing to do so.
Once it’s right, though it is a valuable new context artifact to include in further problem solving on a domain.
Is there anybody creating Mermaid diagrams with LLMs, especially? I tried with Claude and R1 (ProxyAI plugin for Jetbrains) and I had to find the correct phrasing to interact with it. Does the Mermaid-blessed AI have any secret sauce or can I instruct any LLM?
Re: LLMs & diagrams - in general, diagrams and tables as info compression tool (both in the general sense as well as in the practical concrete "optimise for token / context window" sense) - e.g. today as part of request to do 'deep research' on Dwarf Fortress personality / psychology system, at a late point (preparing to relaunch with a fresh empty context window among other things) I asked GPT 4.5 to (among other diagrams) draw me a concise 'psychological data flow diagram' (I was kind of vague and was deliberately pushing for abstraction / compression) -
among (many elaborate) other things it gave me - and I liked it (NB don't trust it willy nilly w.r.t. the below of course) - (auto-indented by 2 spaces hope formatting works) =>
```
```p.s. it chose the syntax/format itself; regardless, some time ago when asked for guidance re: how to manage sliding context window, it did suggest tables itself (user employing them for concise input - and likewise requesting tabulated/diagrammatic/schematic output).
p.p.s. (edit) many good very particular insights, if anyone's by chance interested then lmk, I'll ping once distilled interesting output is on a not-yet-extant blog (it's gonna happen finally)...
Don't mean to be blunt, but I found your comments really hard to comprehend. Something about the phrases feels atypical, almost like it's a different dialect. Curious if it's just me.
This is useful feedback for me. Thanks (no further comments, but I think I know the reason why it's been this way especially as of late)
Never know we can format comment like this in HN :o
Mermaid is also supported in GitHub, GitLab, and IntelliJ. Use it; a diagram is worth a thousand words.
https://github.blog/developer-skills/github/include-diagrams...
https://handbook.gitlab.com/handbook/tools-and-tips/mermaid/
https://plugins.jetbrains.com/plugin/20146-mermaid
Never seen a bigger waste of time than when my colleague (who was given more authority for some reason) tried establishing Mermaid as our go-to diagramming tool for the company.
Had no real benefits, was way more cumbersome for almost everyone and honestly even me as a developer I'd rather have a few paragraphs instead of a diagram.
Somehow it's just never "readable"
I'm curious what you prefer instead?
I find that tools like Mermaid are pretty invaluable, especially when editing very large processes. Draw.io diagrams tend to get pretty unwieldy as they scale and editing inter process stuff if you forgot something quite frustrating.
Sequence diagrams are possibly my favorite feature in Mermaid: https://jessems.com/posts/2023-07-22-the-unreasonable-effect...
Admittedly I primarily use D2 nowadays. The only features I miss in D2 from mermaid are the GitHub automatic rendering and Sequence diagram numbers. https://play.d2lang.com
I use excalidraw, even upgraded to pro out of my own pocket. It's not git-compatible in the sense that it's not text (though you can export to SVG and commit that, which I've done). But I love that it has the feel of an approximation or just a quick sketch rather than a formal promise of how a system works.
When I've used dot or mermaid to build diagrams I've always found it hard to specify layout, colours and sizes, which I use to emphasise different views on a system. I'd love some sort of middle ground where I get the benefits of version control but also the sketch-like character of excalidraw
can it automatically re-flow flowchart layouts?
I'm actually not sure, It's no really a flowchart editor, more of a vector drawing program, though it has some features like being able to pin the end of a line to an object so it follows while you drag
From the post: All diagrams that look like the top image or the mermaid example after the complex one, could just be a list of steps.
For the complex one, maybe yes, it makes sense to have an overview and I think maintaining that vs text is also easier. However from what I've seen, most things can be boiled down to a list of 1, 2, 2.1, etc.
Nowadays I use mermaid, but I only use sequence diagrams. They're incredibly useful to convey to a client at a high-level what are the different workflows in a system.
Had no benefits/was more cumbersome than what?
My colleagues frequently use one of these general-purpose WYSIWYG drawing tools, and I'm not a fan at all – everybody has their own slightly or wildly varying riff on UML or flowcharts, and the result is chaos: Sometimes rectangles are states, sometimes they're decisions; sometimes arrows are labeled state transitions, but other times they're unlabeled and state transitions are also boxes.
Discoverability is also much worse compared to e.g. Mermaid or PlantUML diagrams checked into version control or stored as text source in Wiki articles.
Text, just an ordered list of steps
I also ran into massive issues trying to use Mermaid when I tried to pair it up with Marp (markdown for presentations). I am not sure if it is Mermaid's fault or Marp's fault but it didn't work and tons of people want it to work:
https://github.com/orgs/marp-team/discussions/207
The discussion seems to make it pretty clear where the issues are, though, and how you can get around them using mermaid's render to svg.
So what do you use? Figma?
Commented elsewhere, sorry should have clarified. Just a bit of text, mostly a bit of context of the requirements, potential edge cases and then an ordered list of steps
I have been using mermaid with gpt... describing the diagram I want and getting the syntax, then copy pasting it into the repl. I also wanted to investigate using marp for quickly coding up power point slides. But I regularly ran into issues with customising styles and documentation around html so I gave up on that
I've been asking gpt to use mermaid to diagram before writing the code. It seems to help produce better results.
Is there a visual interface for Mermaid?
I can blast out auto-reflowing flowcharts in Flying Logic on a keyboard but it's moved to a subscription model that doesn't make sense for my irregular use.
Seeing the connections in real time really helps with my thought process.
Using the extension, you can see your changes from the Mermaid Code rendered as a diagram in real-time.
If you also want to interact with the diagram itself to make the changes, you can do that using the Mermaid Chart Playground: https://www.mermaidchart.com/play
Is this new? I remember playing with a mermaid plugin like a year ago.
You are right! A light plugin was released then.
Now, we have added lots of new functionality. Proper editing with syntax highlighting, etc. Apart from that, we have also added integration with GitHub Copilot, so you can generate diagrams from code and continue to edit them using the extension.
I have been using it lightly. But the biggest problem (for me) is that I cannot use custom icons. I have to use Azure specific icons in a lot of diagrams. Mermaid's support for custom icons is only via iconify packs as far as I can tell. Is it possible to refer to icons in a local directory, such as "./images/storage.png"?
That's good feedback. The icons are not bundled into Mermaid itself due to copyright concerns. The approach you suggest would make sense, though.
Does this let you export rendered diagrams at html or pdf? The Markdown Preview Enhanced plug-in is the only plugin I found to do this easily lady time I was looking .
More good input! Appreciate it. What about PNG export? It seems more direct than a PDF to me.
I use a similar plugin for graphviz and PNG and SVG output are used often when exporting the graphs from the tool.
Adding a ticket for this :)
Installed it, ran "@mermaid-chart make a diagram of the code flow in this file" in CoPilot, worked like a charm. Cool!
Does it work with display(Markdown(...)) in jupyter notebooks within VSCode?