I love mermaid because it’s so easily source-controlled. It also has pretty solid documentation.
Don’t love that each diagram type typically has significantly different syntax.
Also don’t love (as mentioned by another commenter) the lack of control over layout—yea there are some advanced options for this but I find them obscure and difficult to configure.
I did create an internal tool that scans my Firestore data model and outputs an ER Diagram in mermaid. Works really nicely for that.
There's basic layout issues that can drive users mad.
I wanted to left justify text[1] in a note for a sequence diagram. It only worked in their live editor vs their cloud-backed web app because only the former exposes styling.
Mermaid is great for simple stuff. If you want a more advanced approach where you can even have multiple levels. Lool at c4. The best way to do c4 without paying a dime I think is https://likec4.dev/
But again, for simple stuff, mermaid! It's also natively supported in a lot of markdown renderers, like gitlab
Indeed they do. It works but it is not great. I tried it for a couple of projects but eventually switched away from it because the layout renderer is pretty bad at this time and the results are not aesthetically pleasing at all, at times being difficult to read because the layout algorithm is so bad.
There's also PlantUML (lots of ads on the page, unfortunately) with support for all sorts of diagram types, and it's extensible. Swimlane, UML, sequence and about 20 more.
LikeC4 looks really cool. I spent a little time with the documentation and it seems like it requires that it runs its own server to render the diagram. In other words no export to html or svg. Do you know if that's the case?
I used MermaidJS for diagrams in one of my projects.
Initially it was fun, although MermaidJS lacked support for the diagram types I used at that time.
What stooped to be fun, is that MermaidJS needs a whole Chromebrowser engine to render the diagrams and it is built on Node.js.
Trying to generate my diagrams in another environment again was a total PITA and not worth the time.
I would love if the MermaidJS devs would port everything to another tech stack, don't use a whole browser engine to render their diagrams and make diagram creation easy and reproducible for build piplelines.
> make diagram creation easy and reproducible for build piplelines.
Up to you, but PlantUML is one .jar file and thus very easily renders in a pipeline. So, between waiting for MermaidJS(!) to port everything to another tech stack or using a tool that has a ton more diagram types than Mermaid and has an offline render tool ... up to you
That's the complaint. Have fun trying to get attractive and reprodicible headless CI builds. I still have some issue with font rendering using latest version of their cli.
MermaidJS is pretty cool. I used it at several previous organisations to document flows between services, internal data flows, and other kinds of diagrams.
The fact that it's written in plain text makes it ideal for versioning with git. You can ever update the diagram in the same patch that changes a flow.
This website design seems to be new, and it's quite disappointing that there's not a single diagram in sight. It seems like a missed opportunity, where the whole page could be filled with examples (both in text form and the rendered version).
Agree but we are changing things up to make this easier.
In the upcoming Mermaid version 11, we are adding a way to select which layout algorithm is used to layout the diagram. We are also making it easier to add additional layout algorithms.
Mermaid could do well to learn from Graphviz. It’s much older and a lot of thought has been put into rendering. It’s the most powerful graph rendering engine that I’m aware of and for anything more than a little complex it’s really the only option to produce something even readable.
I tried to migrate to Mermaid, but despite all the disadvantages, I found that PlantUML + IDE Extension are superior in terms of syntax, diagram variation and visual customisation.
The lack of control on the layout can sometimes be a feature. If something starts to look bad, I often use it as a sign that my architecture is wrong. I’ve found that many times it’s helped point me in a better direction. If it’s easy for the graph layout engine, it’s probably a better architecture.
I mean, one click takes you to "Get Started" which then has some of the best docs I've seen in a long time. Put together and created by the people you saw on the first page?
I've been using this to diagram state machines while talking about complex UI/state flows at work and people are amazed at how quick and efficient it is as a real time presentation tool.
I hate most of the color themes, but the tool is pretty good and chatGPT understands the syntax so you can have some constructive diagramming conversations with the robots.
Yup. In fact, one of the first wow moments for me when using multimodal ChatGPT was snapping a picture of an old diagram that I had written in faded pencil and asking GPT to convert it to mermaid syntax which it did flawlessly.
Mermaidjs is amazing. you could ask LLM to visualise your question (e.g codebase) using mermaidjs syntax and it mostly works just fine without any syntax errors. or at least on Claude Sonnet 3.5 from my experience
I created a front-end application + Ollama where, when you input a book name, it generates a graph using Mermaid, illustrating all character relationships
We use mermaid for our charting in our technical documentation (which is public facing). Mostly object diagrams and sequence diagrams. Moved from plantUML, which I still miss some days.
Love the ability to version control your charts as well as write them out quickly without involving a design team and still have them look pretty good.
[0] https://docs.gitlab.com/ee/user/markdown.html
[1] https://github.blog/developer-skills/github/include-diagrams...
Looks like Colab almost does.
The official vscode MermaidJS extension probably could work in https://vscode.dev/ : https://marketplace.visualstudio.com/items?itemName=MermaidC... :
LLMs can generate MermaidJS in Markdown diagrams that can easily fixed given sufficient review.Additional diagramming (node graph) tools: GraphViz, Visio, GSlides, Jamboard, yEd by yworks layout algorithms, Gephi, Dia, PlantUML, ArgoUML, blockdiag, seqdiag, rackdiag, https://markmap.js.org/
Don’t love that each diagram type typically has significantly different syntax.
Also don’t love (as mentioned by another commenter) the lack of control over layout—yea there are some advanced options for this but I find them obscure and difficult to configure.
I did create an internal tool that scans my Firestore data model and outputs an ER Diagram in mermaid. Works really nicely for that.
I wanted to left justify text[1] in a note for a sequence diagram. It only worked in their live editor vs their cloud-backed web app because only the former exposes styling.
1. it's otherwise locked to center justified
But again, for simple stuff, mermaid! It's also natively supported in a lot of markdown renderers, like gitlab
Ilograph https://app.ilograph.com/
Structurizr https://structurizr.com/dsl
[0] https://icepanel.io/
Initially it was fun, although MermaidJS lacked support for the diagram types I used at that time.
What stooped to be fun, is that MermaidJS needs a whole Chromebrowser engine to render the diagrams and it is built on Node.js.
Trying to generate my diagrams in another environment again was a total PITA and not worth the time.
I would love if the MermaidJS devs would port everything to another tech stack, don't use a whole browser engine to render their diagrams and make diagram creation easy and reproducible for build piplelines.
Up to you, but PlantUML is one .jar file and thus very easily renders in a pipeline. So, between waiting for MermaidJS(!) to port everything to another tech stack or using a tool that has a ton more diagram types than Mermaid and has an offline render tool ... up to you
Wrote an article about it: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...
That's the complaint. Have fun trying to get attractive and reprodicible headless CI builds. I still have some issue with font rendering using latest version of their cli.
The fact that it's written in plain text makes it ideal for versioning with git. You can ever update the diagram in the same patch that changes a flow.
This website design seems to be new, and it's quite disappointing that there's not a single diagram in sight. It seems like a missed opportunity, where the whole page could be filled with examples (both in text form and the rendered version).
[0] https://learn.microsoft.com/en-us/azure/devops/project/wiki/...
I'm leading a data warehouse migration and I keep wishing that ER diagrams were just as easy to write as ETL data pipeline diagrams.
- Can be embedded as code blocks in straight markdown notes (and many markdown editors support rendering)
- Since it's not a graphic, it's text searchable
Mermaid Cons
- if you don't like the way the diagram is visually laid out there's not really an easy way to change it
In the upcoming Mermaid version 11, we are adding a way to select which layout algorithm is used to layout the diagram. We are also making it easier to add additional layout algorithms.
Hopefully, this will be easier going forward!
Love the ability to version control your charts as well as write them out quickly without involving a design team and still have them look pretty good.
It is especially nice combined with mkdocs and the mermaid plugin when doing documentation.
It is a great tool for diagrams