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

131–140 of 272 posts

Re: Include diagrams in your Markdown files with Mermaid

#131

Post by prpl »

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…

There is also https://github.com/asciitosvg/asciitosvg

Used in zeromq docs.

Re: Include diagrams in your Markdown files with Mermaid

#132

Post by mintplant »

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…

Alright, but how do I embed highlighted Mermaid source code in Markdown now?

Re: Include diagrams in your Markdown files with Mermaid

#133

Post by Jtsummers »

anderspitman wrote: post #121
didericis wrote: post #109

Earlier quoted context omitted.

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.

I don't think GP was suggesting that there's anything specific wrong with GFM, but more that the way github encourages READMEs to be used (by auto-rendering all READMEs to HTML) creates an abstraction that shadows the readable-as-text goals of markdown.

> readable-as-text goals of markdown.

Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). It's name is a punny joke, but it's a lightweight markup language that was meant to be a lightweight way to write formatted text that would be rendered as formatted HTML. GFM seems in keeping with this for the most part.

Re: Include diagrams in your Markdown files with Mermaid

#135

Post by w4rh4wk5 »

schemescape wrote: post #123
w4rh4wk5 wrote: post #65

Semi-related question: does mermaid-cli still bring along chromium to 'render' images?

Yes, it uses browser APIs (e.g. SVGGraphicsElement.getBBox()) to measure text, compute transformations, etc. I had hoped to use Mermaid in a static site generator to create SVG diagrams at build time (to avoid requiring JavaScript), and this dependency was irritating enough that I abandoned Mermaid entirely and instead compiled Graphviz to WebAssembly (and honestly I prefer Graphviz's syntax, although it doesn't supp…

Yeah, I was wanted to use the Git graph feature to create some nice diagrams. I expected the cli to work just like graphviz. Yet I was greeted by a stacktrace from Chromium since it did not work in WSL.

The whole idea of depending on a full blown Chromium for your cli tool just to convert that mermaid description into an SVG or PNG seems bad to me. It was my personal turning point where I stopped using JavaScript based tools in my toolbox.

Re: Include diagrams in your Markdown files with Mermaid

#136

Post by avgcorrection »

Jtsummers wrote: post #133
anderspitman wrote: post #121

Earlier quoted context omitted.

I don't think GP was suggesting that there's anything specific wrong with GFM, but more that the way github encourages READMEs to be used (by auto-rendering all READMEs to HTML) creates an abstraction that shadows the readable-as-text goals of markdown.

> readable-as-text goals of markdown. Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). It's name is a punny joke, but it's a lightweight mark up language that was meant to be a lightweight way to write formatted text that would be rendered as formatted HTML. GFM seems in keeping with this for the most part.

> Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). [...] meant to be a lightweight way […]

No, that was not the primary design goal.

> The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.

https://daringfireball.net/projects/markdown/

Re: Include diagrams in your Markdown files with Mermaid

#137

Post by perth »

I love Mermaid! I used to use that bitch all the time in college to make beautiful flowcharts and my friends would always ask me how I made them so nice looking. Another awesome thing about Mermaid is since it’s grounded in the HTML/CSS/JS web stack you can easily modify certain things in diagrams to do any custom tricks you need for your specific diagram. Aka Mermaid is hackable and I love software that is designed to give you that freedom.

Re: Include diagrams in your Markdown files with Mermaid

#138

Post by Jtsummers »

avgcorrection wrote: post #136
Jtsummers wrote: post #133

Earlier quoted context omitted.

> readable-as-text goals of markdown. Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). It's name is a punny joke, but it's a lightweight mark up language that was meant to be a lightweight way to write formatted text that would be rendered as formatted HTML. GFM seems in keeping with this for the most part.

> Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). [...] meant to be a lightweight way […] No, that was not the primary design goal. > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up…

> Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Literally the first paragraph from your link. I'm having trouble reconciling that first paragraph with the idea that it wasn't meant to be rendered as HTML.

Re: Include diagrams in your Markdown files with Mermaid

#140

Post by dijit »

brainfish wrote: post #117
dijit wrote: post #92

Earlier quoted context omitted.

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.

I think this is a false equivalence. The content of SVGs is non-semantic; to get from SVG code to Meaning one needs to do some sort of rendering and re-interpreting of the resulting image. Even if for some simple images that could be done in-brain, that is not usually the case. Whereas something like Mermaid is intended to be meaningful both as code and as rendered output, just like Markdown itself. Having that addit…

I don't know if it's a false equivalence, because I've read (and certainly written) a fair number of mermaid diagrams which are extremely hard to understand without seeing the rendered content.
Post reply on HN