gcp-icons-for-plantuml VS mermaid

GCP.

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.

I like Mermaid[^1], but can’t be bothered to learn the syntax. So, most of the time, I ask LLMs to generate the scaffolding and work from that.

For freehand drawing, to me, nothing beats Excalidraw[^2]. I use it for pretty much everything—from system design work to planning a project and explaining a concept. Such a wonderful tool from the Czech Republic.

[^1]: https://mermaid.js.org/

[^2]: https://excalidraw.com/

Mermaid is an open-source JavaScript library that allows users to generate diagrams and charts from plain text in a simple and intuitive way. Using a Markdown-like syntax, it enables the creation of flowcharts, sequence diagrams, Gantt charts, and more, directly within documentation or code. Its main advantage** lies in its ease of integration and ability to automate visual creation, making it an ideal tool for developers and technical teams looking to add charts easily.

Libraries for generating mindmaps from tree-structured text, such as Mermaid and Pintora, are well-known. However, Mermaid does not work on Node.js, and Pintora, which uses native code, is difficult to run as a serverless function. Therefore, I had to write a Web API from scratch to generate SVG diagrams of mindmaps from text.

I think there are two slightly different issues here!

1. SVGs generated by Mermaid use the SVG 2 features, but other than browsers, most libraries only support SVG 1.1 features, i.e. <https://github.com/mermaid-js/mermaid/issues/2102>, which is what the other comment mentioned.

2. Mermaid requires a browser layout engine to render the diagrams (your issue), i.e. <https://github.com/mermaid-js/mermaid/issues/3650>. This is something I also really want to fix (I maintain the [`mermaid-js/mermaid-cli`][1] project and we need to use Puppeteer/Headless Chrome to render mermaid diagrams, which isn't ideal.) However, I don't think this would be easy, since we'd need a browserless tool that supports a browser-like layout engine (although I'm hoping that [Servo][2] might eventually be able to support it).

And if you do want to do headless renders of Mermaid diagrams, I'd recommend using (or adapting, since the code is all MIT licensed and I'm not aware of one that uses Selenium):

- <https://github.com/mermaid-js/mermaid-cli>, which uses Puppeteer as the headless browser API.

My "Documentation as Code" series took an unexpected turn. While I initially was a Plantuml advocate, I found myself gravitating more and more towards Mermaid charts (also after having to write some ADRs where, of course, I've added some diagrams). Its seamless integration with GitHub - automatic rendering in Markdown documents 😎 - proved to be a killer feature.

Good architecture prioritizes transparency and understanding. Tools such as vFunction or Dash0 can bring your architecture out of the shadows and into the light. Both of these offer architectural observability capabilities that help visualize your codebase, revealing service boundaries, interdependencies, and areas of inefficiency. With vFunction, teams can document complex microservices in real time, making it easier to spot bugs and bringing architecture-as-code to life with support for tools like Mermaid for sequence diagrams and automatically validating the actual architecture against manually created C4 diagrams for system modeling.

With the rise of AI-powered tools, creating these diagrams has never been easier. In this post, I evaluate some of the most popular AI-enabled diagramming tools, including Miro, Excalidraw, Figma's FigJam, ChatGPT (with Mermaid). My goal is to see how they perform when tasked with real-world developer scenarios like sequence diagrams or database ERDs.