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

101–110 of 272 posts

Re: Include diagrams in your Markdown files with Mermaid

#101

Post by spoils19 »

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.

RENDERME, nice one!

Re: Include diagrams in your Markdown files with Mermaid

#102

Post by reificator »

qbasic_forever wrote: post #56
reificator wrote: post #41

Earlier quoted context omitted.

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 bloc…

You're pushing a rock up hill--many markdown renderers natively support mermaid, plantUML, etc. using fenced code blocks. If you explicitly want source code rendering don't add the mermaid tag to the block. There could be an argument that now you don't get syntax highlighting, but remember syntax highlighting itself is not part of any markdown spec and it differs wildly between implementations--there is no common gra…

> You're pushing a rock up hill--many markdown renderers natively support mermaid, plantUML, etc. using fenced code blocks.

And yet Github's markdown support carries much more weight. Raising concerns at this point is a perfectly reasonable thing to do.

Re: Include diagrams in your Markdown files with Mermaid

#103

Post by actually_a_dog »

throw0101a wrote: post #45
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 kin…

I saw several things that looked promising on Github:

* https://github.com/ivanceras/svgbob

* https://github.com/ggerganov/dot-to-ascii (renders DOT to ascii. Combine this with an SVG renderer, maybe?)

* https://github.com/ivanceras/spongedown

Also, this SO question: https://stackoverflow.com/questions/3211801/graphviz-and-asc...

I'm sure there are more out there.

Re: Include diagrams in your Markdown files with Mermaid

#104

Post by donatj »

With Mermaid, the usage seems very locked down to a handful of use cases.

I want to be able to point a method of a classDiagram at a decision chart with arrows then to the row of a database table.

This is the sort of thing I reach to either Graphiviz or for Omnigraffle currently, and this doesn't seem to solve.

With Mermaid each type of diagram is distinct and locked down to specific intended uses.

Re: Include diagrams in your Markdown files with Mermaid

#106

Post by Arnavion »

dijit wrote: post #92
Arnavion wrote: post #80

Earlier quoted context omitted.

It's nice to have the diagram source in the same file that uses it, instead of a separate file that needs to be kept in sync.

Since it’s sufficiently different to how it’s rendered its really more like an SVG than a table. So, the question is would you rather have SVGs inline? Personally I think the reference to another file is a perfectly fine compromise, as the content is sufficiently different to no longer be markdown.

It's subjective, in my opinion. I might be fine with inline SVGs if they were "smaller", ie didn't have the doctype and root element and general XML verbosity on all nodes. PlantUML / Mermaid have a much more to-the-point syntax.

Also, I personally hate markdown tables since editing even a single cell means that I likely have to then resize either the entire row or the entire column, or both. So when I do need tables I use HTML tables anyway.

At any rate, a middle-ground might be to have the diagram source as references at the end of the document, and reference those from the use site, like `![Chart][#chart]` or something. So you don't have to see the diagram source inline if you don't like it, but it's still there in the same file.

Re: Include diagrams in your Markdown files with Mermaid

#107

Post by Ciph »

berkes wrote: post #81

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 annoyi…

Another annoyance is how the sync between the editor and preview pane "jumps" uncontrollably when using mermaid. I do however love it too and comitted to use it over other note-taking software.

Re: Include diagrams in your Markdown files with Mermaid

#108

Post by qbasic_forever »

dijit wrote: post #97
qbasic_forever wrote: post #24

Earlier quoted context omitted.

No there's not a formal requirement or spec for how markdown blocks are rendered. Even things like syntax highlighting are optional choices different renderers make (and even the whole idea of highlighting is not specified or defined, how do you define the grammer, etc?). Some tools in the computational notebook space use markdown with fenced code blocks as blocks of executable code, see for example jupytext: https:/…

There is a formal spec (from github themselves) for how it’s rendered. What’s debatable is what the spec does with the “info” section. https://github.github.com/gfm/#fenced-code-blocks

Sure but there's no markdown spec. Markdown is purely a series of blog posts by John Gruber and a collection of different implementations. CommonMark is as close to as it's gotten to a formal spec, and even it says there is no requirement the info string (i.e. text like mermaid after backticks) be interpreted for specific rendering (or not rendering) of the content: https://spec.commonmark.org/0.28/#fenced-code-blocks

Re: Include diagrams in your Markdown files with Mermaid

#109

Post by didericis »

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.

Which specific github flavored features violate the original spirit of markdown? I only use the basic syntax, but I don’t think I’ve run across a readme edit that hasn’t adhered to that original spirit.

Re: Include diagrams in your Markdown files with Mermaid

#110

Post by e12e »

martinwoodward wrote: post #48
e12e wrote: post #21

Earlier quoted context omitted.

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 p…

I don't think github should (generally) render stuff in the browser (although I see that both "benign"[1] graphs and source code highlights, not to mention the somewhat simple translation from Markdown to html - probably could be done in the browser as js/wasm.

But for "markdown the language" having a standard syntax for embed/evaluate along with prettify/highlight would've been nice - effectively a standard markup for multi-language "notebooks"/literate programs (maybe we need a triplet: format, render/embed, transclude/literate programming).

Github could then opt-in to highlighting the N languages they do, and initially only try to render mermaid graphs. Then perhaps also graphviz graphs. Etc.

[1] I'm sure one could do some minor DOS at least with a 500 mb graph..

Post reply on HN