Mermaid: Diagramming and Charting Tool | Hacker News Reader

Mermaid: Diagramming and Charting Tool

mermaid.js.org

174 pointsthunderbong65 comments

Open articleView on HN

A key thing to appreciate is that both Github and Gitlab support rendering Mermaid graphs in their ReadMe's

[0] https://docs.gitlab.com/ee/user/markdown.html

[1] https://github.blog/developer-skills/github/include-diagrams...

JupyterLab supports MermaidJS: https://github.com/jupyterlab/jupyterlab/pull/14102

Looks like Colab almost does.

The official vscode MermaidJS extension probably could work in https://vscode.dev/ : https://marketplace.visualstudio.com/items?itemName=MermaidC... :

  ext install MermaidChart.vscode-mermaid-chart

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/

Also in PR comments. Incredibly handy if you want to help explain something complex you've added for review.

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.

I'm surprised nobody has fixed the layout yet. I often get graph nodes that draw off screen as it easily get too wide too fast.

You summarized well my three complaints about the tool.

Is your tool open source by chance?

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.

1. it's otherwise locked to center justified

Just make some of your relationship arrows longer by adding more dashes.

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

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.

also supports macros

with this plantuml excel plugin, you keep keep all your diagrams in excel and also no need to learn the syntax for couple of plantuml diagram types https://docs.cornerstoneappsolutions.com/getting-started/ https://www.youtube.com/@CornerStoneAppSolutions/videos?app=...

There are also ilograph and structurizr for architecture diagrams.

Ilograph https://app.ilograph.com/

Structurizr https://structurizr.com/dsl

It's not a great look for Ilograph's first example diagram to smash text on top of one another :-/ https://imgur.com/CdJXyYN

It's a known issue with FireFox... at least it only happens on hover.

That's... not better.

Wow! Thanks for sharing this ... Been looking for a FREE C4 diagrammer without paying Simon Brown! LOL

IcePanel has a free tier. [0]

[0] https://icepanel.io/

Mermaid even has experimental support for plantUML-format C4: https://mermaid.js.org/syntax/c4.html

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.

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

its actually does not require node, it runs completely in the browser

> it runs completely in the browser

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.

You can dispense with this if you type it on markdown or an Jupyter notebook and use quarto to render it.

Sounds like you might like D2. It is written in Golang and doesnt use Chrome to render.

Wrote an article about it: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

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).

Another nice thing about Mermaid for those of us working in a .NET ecosystem is that Azure Devops supports it[0].

[0] https://learn.microsoft.com/en-us/azure/devops/project/wiki/...

Feature request for the Azure DevOps team if any are reading this... Could you add Mermaid Entity-Relationship diagrams to ADO?

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.

It's also supported inside loop, just add a code block and select marmaid as a language

Mermaid Pros

- 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

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.

Hopefully, this will be easier going forward!

Will it be possible to manually position the nodes? Ideally, manually position some nodes and auto-layout the rest.

This discussion reminds me a lot of graphviz. Similar issues and (IIRC) proposed solutions.

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.

Nice! Can't wait to try it

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.

I love mermaid but agree the visual customization is too limited for many use cases.

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.

Not just customization—I think PlantUML looks a lot better than Mermaid out of the box.

Same here.

I can't help but notice that the homepage has at least a hundred pictures of humans, and zero pictures of any diagrams or charts.

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?

Same. They should chart those faces.

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.

This site compares a few text-based diagramming tools, including Mermaid: https://text-to-diagram.com

I have a more comprehensive list here https://xosh.org/text-to-diagram/

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

Cool! Consider posting it on ShowHN.

Actually I've never thought about it. It's no complicated app. But I'll clean it up and will post it. Thanks for the idea.

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.

What was the deciding reason to switch from PlantUML to MermaidJS ?

Use mermaid quite often. It's best for simple flow charts, git flows, etc, but where applicable it is great.

It is especially nice combined with mkdocs and the mermaid plugin when doing documentation.

One of its biggest advantages is how widely deployed is it, it is supported by many apps for note taking in a way or another.

Does the CLI tool still pull in chromium to render an SVG?

This is the best thing ive found on the internet this week...

I like to use mermaid diagrams with LLMs, it's very handy to convert any type of text (code, prose) into e.g. a flow chart to viz in mermaid.

I wish Reddit and Old Reddit supported Mermaid natively.

Don't forget that ChatGPT supports the format and you can create diagrams, idea maps, gantt etc in no time!

marimo notebooks support mermaid as well - https://docs.marimo.io/api/diagrams.html#marimo.mermaid

It is a great tool for diagrams

Mermaid is great!

Reply on news.ycombinator.com