Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Include diagrams in your Markdown files with Mermaid

github.blog

Post reply on HN
Print view View original

81–90 of 272 posts

Re: Include diagrams in your Markdown files with Mermaid

#81

Post by berkes »

Joplin, the Open source note-taking app¹, has Mermaid built-in.

I use those a lot when keeping my notes on arcitectures, design patterns and software design. I prefer this, vastly, over Google Docs + draw.io.

The only thing I dislike about Mermaid-in-Joplin is that the live-pre-render of the actual chart fails and shows an error whenever there is an error in the source of the diagram. Which makes sense. But is annoying because *when you are typing out the syntax, there always is an error untill you finish the class, object, some bracket or relation.

¹https://joplinapp.org/ EDIT: I'm not affiliated to joplin in any way. Just love it.

Re: Include diagrams in your Markdown files with Mermaid

#82

Post by Someone »

I like markdown, and can see the lure of additions such as this one, but I also sometimes wonder whether we gained much compared to troff and its companion programs (pic, eqn, tbl, chem, etc. See https://www.troff.org/prog.html).

If we added Unicode support and html and pdf output to those, I think the main thing we would miss is readability of the raw text. That doesn’t look like much progress in half a century.

Re: Include diagrams in your Markdown files with Mermaid

#83

Post by pizza234 »

mongol wrote: post #40

Mermaid looks similar to PlantUML. Anyone that gave used both and can compare?

In the past I used to use Mermaid for simple (but not trivial) flow charts and class diagrams.

I've found some minor rough edges, but in particular, a couple of missing features, one of which I needed (edges going from attribute to attribute in class diagrams).

PlantUML didn't have any of those limitations, so I switched, and never looked back.

For simple-but-not-trivial diagrams, I didn't find any substantial difference in terms of syntax (complexity). I don't have experience on complex diagrams, though.

Re: Include diagrams in your Markdown files with Mermaid

#85

Post by Steltek »

berkes wrote: post #75
avgcorrection wrote: post #32

I think so-called ASCII-art is more in the spirit of Markdown. The nice thing about the original Markdown (modulo bugs) is that things are written the way one would write plaintext documents which are supposed to be easily read in a text editor. So you don’t write bullet lists like this: - Bullet 1 - Bullet 2 - Bullet 3 And hope that some post-processing will add linebreaks for you. You write it like this: - Bullet 1…

While I agree, formatting languages like Mermaid or PlantUML are human readable enough to grasp them and their meaning from reading the textual form. And, as others below point out, editability is another great treat of Markdown. ASCII charts are very hard to format; you'll really need tools or editor plugins for that. So I think that Mermaid (and PlantUML) strike a very pragmatic and human-friendly balance. Which, I…

> ASCII charts are very hard to format; you'll really need tools or editor plugins for that.

Even with tools and plugins, creating tables in Markdown (in any flavor) is painful enough that I just don't even try. No one really expects to edit an image with a text editor but tables are tantalizing close.

I'd sooner have ASCII inspired tables that are easier to edit than images and diagrams.

Re: Include diagrams in your Markdown files with Mermaid

#88

Post by Someone1234 »

no-dr-onboard wrote: post #58

Protip to anyone using Mermaid.js Don't. It's a sea shanty of XSS vulns. https://snyk.io/vuln/npm%3Amermaid

Does this mean it is bad or simply popular? Unpopular/untested libraries rarely have previously found XSS vulnerabilities for example.

Re: Include diagrams in your Markdown files with Mermaid

#89

Post by mafro »

moolcool wrote: post #52
avgcorrection wrote: post #32

I think so-called ASCII-art is more in the spirit of Markdown. The nice thing about the original Markdown (modulo bugs) is that things are written the way one would write plaintext documents which are supposed to be easily read in a text editor. So you don’t write bullet lists like this: - Bullet 1 - Bullet 2 - Bullet 3 And hope that some post-processing will add linebreaks for you. You write it like this: - Bullet 1…

To that point, ASCIIFlow is an amazing tool which I use constantly when working on markdown files https://asciiflow.com/#/

Nice tip! I use Monodraw which is macOS only

Re: Include diagrams in your Markdown files with Mermaid

#90

Post by donatj »

WalterGR wrote: post #14
jonpalmisc wrote: post #11

I think this is a good change. While I would have preferred to see support for Graphviz over Mermaid, I understand Mermaid was probably chosen for the sake of easier integration. Either way, it will be nice to be able to embed diagrams rather than constantly re-generate and re-commit images to the repo.

Has Graphviz been re-implemented in JavaScript or compiled to WASM?

It's a simple well documented language. Righting a fully functional JS Graphviz parser from scratch would take a couple days at most.
Post reply on HN