Hacker News Reader

Comment by stakkur | Hacker News Reader

Thereby creating a hard dependency for your markdown files, obviating their portability.

There's no hard dependency at all. The markdown will parse just fine without mermaid.js, it basically just takes a code block and runs it through the mermaid.js code if it matches the language

I'm not talking about a dependency for the file to be readable. I'm talking about a dependency for the diagram to be useful. I'm not opposed to extending markdown, but most functionality like this seems to involve bolting on external dependencies to take advantage of it.

So you want every markdown parser to support building diagrams as well? That seems much more difficult than offloading it to an open source library. Why waste effort that already has gone into building an easy to read diagraming language?

I'm pretty sure stakkur means mermaidjs is a bad option for markdown, as its source form is not "useful" as a diagram, and that it's actually GitHub which is saying every "markdown parser (/renderer) should support building diagrams as well" since they're encouraging its use by supporting the syntax.

The real criticism of the original comment is that markdown has never really been "portable"; yes there's now a hard dependency (for some definition of "hard") on mermaidjs for GitHub-flavored-markdown, but that actually brings it in line with other implementations. So has portability been obviated or just slightly changed?

There's also been other Markdown renderers that support this exact syntax for Mermaid blocks for ages. I have a site that's generated using mkdocs that uses Mermaid diagrams, and I was able to open up one of the files from that site in Github and view the diagrams.

The alternative is no diagram at all, which sucks for understanding, or linking to an image that's likely just a binary blob which is now a hard dependency on your markdown file too. Mermaid is a great fit, it's a text description of common graph types and it's meant to be read, written, and understood by humans in text form.

Reply on news.ycombinator.com