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

41–50 of 272 posts

Re: Include diagrams in your Markdown files with Mermaid

#41

Post by reificator »

qbasic_forever wrote: post #29
reificator wrote: post #22

Earlier quoted context omitted.

Which is the exact inconsistency under scrutiny here.

Markdown supports arbitrary HTML, you can do this: # Heading const foo = 1 + 1; window.alert(`1 + 1 = ${foo}`); Paragraphs of exposition. In practice most markdown renderers will strip HTML or at least script tags as it is obviously a cross site security risk to allow github.com to serve user uploaded scripts without sanitization.

I think you're caught up on exactly the opposite of the complaint here. People aren't requesting JS execution, they have the various "notebook" solutions for that.

People are saying that triple backtick fenced code blocks are used to preserve whitespace and fixed width, usually with syntax highlighting as a bonus. That's the expected behavior.

However with the described mermaid support, it's taking a fenced code block with a mermaid tag and transforming it into a graph.

When inspecting the text content of a markdown file, there's no difference between a `javascript` tagged code block, a `haskell` tagged one, and a `mermaid` tagged one. But now when rendering, the mermaid one is special cased.

This is undesirable for multiple reasons, the most obvious being that it's now harder to write a README that displays mermaid syntax.

A good starting point would be either different syntax or a different tagging convention. For instance I think I saw `!mermaid` suggested, where the `!` would mean that the code should be interpreted instead of rendered as code.

I don't have a horse in the race of what this looks like, only that there should be a distinction between rendered and interpreted code blocks.

Re: Include diagrams in your Markdown files with Mermaid

#42

Post by sidharthv »

ghostoftiber wrote: post #30

I want a lucidchart or drawio style support for mermaid. There's plugins to let them render mermaid.md files but I haven't seen anything which just lets me draw arrows between shapes and label things. Someone please make this happen, I will be forever grateful.

Would you be willing to file a feature request in https://github.com/mermaid-js/mermaid-live-editor/issues ?

Disclosure: I'm a maintainer for the project and the feature will be a bit tricky, but should be doable.

One issue is that unlike drawio, mermaid doesn't support custom placement of nodes. We could have different style arrow popups, which could render corresponding connections in default locations.

I also feel that this would be a very nice feature to have.

If anyone is interested in implementing, please let us know, and we can discuss ideas.

Re: Include diagrams in your Markdown files with Mermaid

#43

Post by daptaq »

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…

The "spirit of markdown" has long been abandoned by GitHub, more often than not the offline readability of a README is absolutely ignored in exchange for a safe-HTML subset to create kind-of websites below the directory listing of a repository.

It should really be called RENDERME.

Re: Include diagrams in your Markdown files with Mermaid

#44

Post by Ciph »

mongol wrote: post #40

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

They are quite similar, PlantUML has support for more types of diagrams than mermaid (such as network diagram), but IMO PlantUML is "messier" to write, I find Mermaid more elegant in writing diagrams.

Re: Include diagrams in your Markdown files with Mermaid

#45

Post by throw0101a »

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…

> I think so-called ASCII-art is more in the spirit of Markdown.

If you're simply doing a less on a file, then sure. But if you want to do a 'render' on the Markdown and convert it to another format (HTML, PDF) then having a mechanism that can translate ASCII to something graphical could be useful.

In some ways this is what the DOT language does in Graphviz:

* https://graphviz.org/gallery/

> The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal.

I'm not sure if there's a way to have both ASCII art and it be renderable to graphics. Closest that I could find:

* https://github.com/martinthomson/aasvg

Re: Include diagrams in your Markdown files with Mermaid

#46

Post by avgcorrection »

daptaq wrote: post #43
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…

The "spirit of markdown" has long been abandoned by GitHub, more often than not the offline readability of a README is absolutely ignored in exchange for a safe-HTML subset to create kind-of websites below the directory listing of a repository. It should really be called RENDERME.

> It should really be called RENDERME.

Hah—yes!

Re: Include diagrams in your Markdown files with Mermaid

#47

Post by mminer237 »

timwis wrote: post #9

I’m super excited for this! One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md: ```js const foo = 1 + 1 ``` Rendered as: `2` ? Isn’t that kind of what we’re doing here with the mermaid source tag? That tag is for showing source code, no? Feels like there should be another tag for rendering it.

I agree. R Markdown has R code execution as part of it's Markdown flavor and it distinguishes code block vs code execution as ```R vs ```{R}

Re: Include diagrams in your Markdown files with Mermaid

#48

Post by martinwoodward »

e12e wrote: post #21
qbasic_forever wrote: post #13

Earlier quoted context omitted.

Only the mermaid identifier is supported for triple backticks blocks, you can't put js and have it spit out script that executes in the browser.

I think op meant that we can: ```ruby # syntax highlighted as ruby a = 1 + 1 ``` And: ```js // syntax highlighted as js a = 1 + 1 ``` So maybe we should have something like a "bang" prefix to evaluate and inline/embed like: ```!ruby # evaluated as ruby a = 1 + 1 # renders 2 because of implicit return? ```

The idea of the bang syntax came up. https://talk.commonmark.org/t/mermaid-generation-of-diagrams...

But in the end went with simple. There will be a very limited subset that will render this way - executing raw code without the users permission in the browser just opens up too much attack surface area that we’d need a very compelling use case to do the security work necessary to make it protected (even if that was possible)

Re: Include diagrams in your Markdown files with Mermaid

#50

Post by raman162 »

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…

I agree that ASCII-art definitely is more cenetered around the original markdown spirit but I personally struggle making my ASCII-art diagrams in Vim. Looking at the mermaid, syntax it looks like I can whip up something equivalent really quick. As a developer I also don't mind that the mermaid syntax reads like pseudocode so it's probably easy for me to digest.
Post reply on HN