Pele – Mermaid diagrams as themeable SVG

Posted by dchest 4 days ago

Counter591Comment61OpenOriginal

Comments

Comment by lukeify 4 days ago

Anytime I try mermaid for anything more complex than a toy diagram I always end up absolutely frustrated by the arcane and topologically poor layout that is produced.

Styling seems like a trivial problem by comparison.

Comment by kepano 4 days ago

I strongly agree, and that's why I designed Pele to only follow its syntax not its layout. See the examples https://pele.run/examples

The playground also has a Compare mode https://pele.run/playground

Comment by DenisM 4 days ago

The layout quality is very impressive!

Have you given much thought to diffing diagrams? The source can be version controlled and a source diff can be seen, but a visual diff would be amazing and easily sway me from writing prose to writing diagrams.

Comment by nkmnz 4 days ago

I've tested a couple of diagrams that I found on some website and I couldn't see any major differences in the layout. Can you point to some systematic differences?

Comment by WhrRTheBaboons 3 days ago

FYI, first two examples are identical here: https://pele.run/examples/timeline

Edit: So is #7 (and almost #8), #9, 10, 11, 12 are identical as well

Comment by krat0sprakhar 3 days ago

This is so so awesome! I always find Mermaid hard to read but Pele is a delight. Just sponsored you on Github as a small way of saying thanks for Pele. Thank you so much kepano

Comment by CrimsonRain 4 days ago

Could you not make Pele part of Marmaid or they wont accept a contribution like this?

Comment by blazarquasar 4 days ago

To quote another reply regarding mermaid by @kepano:

> Mermaid.js has transitioned to "mermaid.ai" and is losing its original vision. Take a look at their new site.

> The latest version of Mermaid (12.1) ships with yet another layout engine (three now), and has a questionable safety record (see CVEs). In Obsidian 1.13 we had to introduce a new toggle/warning because of potential unsafe Mermaid diagrams.

https://x.com/kepano/status/2111575190081847776

Comment by kingstonTime 4 days ago

[flagged]

Comment by ferroman 4 days ago

Then you may like tool I use https://ferroman.github.io/diagc/

Comment by tptacek 4 days ago

Graph layout is a famously hard problem!

Comment by mcapodici 4 days ago

I wonder if it is almost like writing. In that to make the diagram that communicates well you need to have solved the problem properly.

Comment by alfiedotwtf 4 days ago

A common layout implementation is to provide constraints to a SAT Solver… so you were close :)

Comment by wongarsu 4 days ago

To my taste, most automatic layout implementations produce horrible layouts. Yes, you can use SAT-solve and optimize your way towards a node ordering that produces no crossing lines, but those rarely create something that makes intuitive sense of the content

Good layout is a lot more like writing, in that you have to think about how the intended recipient will perceive and what you want them to notice in which order, and how to make it easy to follow the various relationships

Comment by thegagne 4 days ago

I have had good luck with D2 and elk or dagre. If you get into the nitty gritty of elk you can do a _lot_ with it.

Comment by jhoechtl 4 days ago

The tala layout engine for d2 is now included it provides a very good layout.

Comment by jeffreygoesto 4 days ago

If only it had a good documentation. I really like the elkjs JavaScript version (thanks, Ulf!) bitte unfortunately transcoding makes transferring the Java docs even harder...

Comment by kylepomykala 4 days ago

I have the same issue. A neat trick is to have it so the large language model creates an HTML file with what you need inside of it too. That allows for even more flexibility.

Comment by jd3 4 days ago

I don't even bother writing mermaid by hand when I'm making decision trees. Instead of visualizing it using PrecisionTree in excel (I just use that for the actual data modeling), I've been first modeling the tree in plaintext, then pipe it through claude with a previous tree I've made as reference. I then ask it to use the content of the current tree and match it to the style of the previous one.

Comment by giancarlostoro 4 days ago

I kinda just shove what I want out of it to literally any basic model from the frontier labs, I usually dont need anything super fancy, but it does the job, even color coded regions for me (which is fancier than I usually do) and then I can shove that into Lucid since it can render them.

Comment by m-p-3 3 days ago

I found I had better results with D2, sadly not as ubiquitous as Mermaid.

Comment by subfocal 3 days ago

I like TikZ for this.

Comment by oliveralbertini 4 days ago

[dead]

Comment by Imustaskforhelp 4 days ago

Is pele open source?

I tried to find the source code of it but I was unable in finding so

Edit: found it, https://github.com/obsidianmd/pele

Also folks, this is a good reminder to please have a github icon on the top of the page to easily show git/github links if the app is open source, also helps in the fact that I can star your projects and bookmark them more easily :-D

Comment by blktiger 4 days ago

Looks like https://github.com/obsidianmd/pele maybe?

Comment by burgeonlab 4 days ago

I've switched to D2Lang for its easier syntax and the fact Mermaid is hard pushing AI. Appreciate it, Kepano, for making Mermaid a bit more palatable!

[1]: https://d2lang.com/

Comment by whimsicalism 3 days ago

tech that approaches new change with curiosity rather than pseudo-religious turning away will win out because of the type of people who are building the former

Comment by skydhash 3 days ago

> tech that approaches new change with curiosity rather than pseudo-religious turning away will win out because of the type of people who are building the former

Why not

  tech that approaches new change with religious recklessness rather than critical thinking will lose out because of users that are tired of regressions and breakages.

Comment by montroser 3 days ago

Well, not that one, because that one is incorrect.

Adoption of coding agents is motivated by understanding and productivity. That's not traditionally a religious aspiration.

In software engineering, and in so many other settings too, LLMs can act as a strong catalyst, or strong damper for curiosity and critical thinking. The same way that when you used to find a thread on StackOverflow about the exact problem you were facing, you could either copy/paste the solution and forge ahead, or else use those breadcrumbs to research and more deeply understand the problem and its prospective solutions -- you can drive the model to the same effect.

If you are looking to think critically, it can be an absolutely fantastic partner in that endeavor. If you are looking to slap together a solution for a problem you don't care to understand, it can do that too. How you want to use it is up to you. And how other people use it can and will be everywhere across that spectrum.

Comment by skydhash 3 days ago

> If you are looking to think critically, it can be an absolutely fantastic partner in that endeavor.

Joining “thinking critically” and a tool that has no truth basis is concerning. You may as well put numbers inside a raffle box and just take one out instead of using a calculator.

There’s no definition of correct that LLM tooling enforces, so how can it be a partner in thinking?

That’s the main issue with slop coding. It would be way more useful to send pseudocode out if you can. Logical semantic is always independent of programming syntax. No need to generate code.

Comment by montroser 3 days ago

> Joining “thinking critically” and a tool that has no truth basis is concerning. You may as well put numbers inside a raffle box and just take one out instead of using a calculator.

LLMs can have as much truth basis as humans have. We humans have fallible memory, all manner of cognitive biases, varying degrees of deceptive tendencies, misunderstandings, heartfelt beliefs in things we cannot prove...

And nonetheless, looking at art, reading books, talking to children, interacting with nature -- can all prompt us to question our previous assumptions and productively challenge ideas we might have otherwise thought settled. Seeing these different perspectives, however grounded or not they may be in truth and physics, is part of critical thinking.

A calculator will only get you so far. If you're looking for LLMs to tell you the "correct" answer, then you may be disappointed. But if you want leads to follow, ideas to consider, pointers to existing research, experiments to run, then it can be very helpful, similarly to talking to a very knowledgeable colleague. In the end, so far at least, it's still up to the human to make good decisions, based on evidence.

Comment by gonzalohm 3 days ago

Wait, so by pseudo-religious you are not referring to the people that worship AI like a panacea that will solve all our problems and can't see what's wrong with it? that's odd

Comment by Ancapistani 4 days ago

> A flowchart subgraph keeps its own direction even when it links to nodes outside the subgraph.

This, in and of itself, is sufficient reason for me to switch, even if it were slower than Mermaid.js.

I’ve not even made it through the list yet and I’m sold.

Comment by bilibali 3 days ago

Thank you very much for this!

I use a build script for my static website that renders markdown files into HTML files and swaps out any mermaid codeblocks with rendered SVGs. I used mermaidjs for this but it is very heavy for this purpose (needs an entire chromium instance for the rendering).

This seemed like a perfect fit for my use case and I already swapped it in. I noticed that the layouts were not 1 to 1, but to my pleasant surprise I actually liked the ones Pele renders better than mermaidjs.

Comment by dkga 4 days ago

Brazilian me thought it was an homage to Pelé. I’m glad the text explains the name.

Comment by mxuribe 3 days ago

I'm not Brazilian but i grew up in a world where EVERYONE knew who Pele is (maybe i'm a little old?)...So, i also thought the same, that this was named after him! :-)

Comment by 9dev 4 days ago

Amazing. I just migrated the diagrams on the docs site of a project of mine, and they just look great[0]. Before, I had a combination of mermaid, panzoom, and some minor workarounds to get integrated styling and dark theme work right. Pele not only takes care of all of that, but also manages a nicer layout!

[0] https://cetacean.mazetti.me/authentication#oidc

Comment by kepano 2 days ago

That looks great. I like theming and controls you added to make it feel native to your site.

Comment by neomantra 4 days ago

This was pretty inspiring -- I have been working on file format rendering for a pager in terminal+browser and totally forgot about Mermaid!

Much of the work uses SVG as an intermediary so this Pele pattern works great. OP is a TypeScript project, seems great for that ecosystem.

Searching found this go-mermaid library [1] that operates similarly with SVG its target. We have a Golang TUI picture/SVG widget and a Golang WASM/browser embedder, so I just forked it and had an LLM add a live Mermaid/SVG demo using them [2]. The demo is intended for go-mermaid so it uses its rasterizer, composited to our widget.

(took <15 minutes since I had worked similarly just days ago and had the components at the ready, plus could point at Pele; these LLMs are ridiculous at forging from patterns)

Cool thing is that same visual experience can be had in a terminal if it supports Kitty graphics protocol.

[1] https://github.com/zkrebbekx/go-mermaid

[2] https://neomantra.github.io/go-mermaid/

Comment by nickmain 4 days ago

Does the official Mermaid library still require a full or headless browser environment in order to lay out the SVG? If so, Pele is great news for embedding Mermaid rendering in other places.

Comment by falsaberN1 4 days ago

There is also Merman on Github that outputs a SVG.

https://github.com/Latias94/merman

Comment by dont__panic 4 days ago

Very nice, bookmarked. I built something similar as an Astro plugin using svgdom: https://better-static-sites.github.io/build-tools/mermaid/

It still boggles my mind that mermaid's devs think you need an entire freakin' browser to render an SVG. Sometimes I think people need to be reminded of the fundamentals.

Comment by invokestatic 4 days ago

The python mermaidx library works for this, which works well for generating documentation with embedded diagrams as part of CI/CD but the layout/rendering can sometimes be very wonky. For instance I will have a bunch of connections crossing over each other instead of neatly arranged to avoid it. Changing the layout settings does not fix it so sometimes I will just export it from mmdc and embed a png.

Comment by vb-startr 4 days ago

Nice work...will try to incorporate it in our tools and projects. Dark mode support is a good highlight. I appreciate this work. Please keep it up.

Comment by druvisc 4 days ago

Just FYI, "pele" is "mouse" in Latvian. :)

Comment by hmokiguess 4 days ago

and "skin" in portuguese :)

Comment by apodik 4 days ago

and a football player in brazil :D

Comment by mixmastamyk 4 days ago

Only with an accent on the final é.

Comment by mtros 4 days ago

and "d*ck" in slovak...

Comment by aslakhellesoy 4 days ago

Spade in French

Comment by Duke64 4 days ago

No meaning in german

Comment by BHSPitMonkey 3 days ago

It's also the Hawaiian goddess of fire.

Comment by haburka 4 days ago

Thank goodness. Theming mermaid and using it server side is such a nightmare. I had many issues trying to get it to work competently with CSS variables for dark mode / light dark. This seems way better.

Comment by mlhpdx 3 days ago

I like the approach of rendering directly to SVG, which is what I want -- running layout once and caching the result in the browser or on the server side.

Comment by 4 days ago

Comment by syngrog66 4 days ago

longtime user of GraphViz for that kind of use case but I have a TODO to try programmatic generation of my next software diagram in Inkscape's XML format.

Comment by kinduff 4 days ago

Noting that the mermaid preview in the playground is broken.

Comment by kepano 4 days ago

Broken in what way? It works for me. Do you have any details? Browser, errors, etc?

Comment by kinduff 4 days ago

Here are the details, sorry for not attaching before https://gist.github.com/kinduff/7eb14bf348fdec4e664b59e758d1...

Comment by kepano 4 days ago

Thanks! Investigating...

Comment by shellerik 4 days ago

The examples are not very dark-mode friendly

Comment by 4 days ago

Comment by sog 4 days ago

[flagged]

Comment by WorseIsBetter 4 days ago

[flagged]

Comment by notaproton 4 days ago

FOUC in the big 26 is crazy work

Comment by wolframhempel 4 days ago

Blatant self promotion: But if you'd like your Mermaid diagrams rendered in pretty isometric 3D, we've added Mermaid support to Arcentry lately: https://arcentry.com/blog/isometric-mermaid-diagrams-with-ar...

Comment by dbg31415 4 days ago

Tools like this are so amazing because they allow Claude to edit and draw and save to a single markdown file. So practical! Version control friendly. People can use them, sure. Buy AI can really take off with tools like this.