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

121–130 of 272 posts

Re: Include diagrams in your Markdown files with Mermaid

#121

Post by anderspitman »

didericis wrote: post #109
daptaq wrote: post #43

Earlier quoted context omitted.

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.

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.

Re: Include diagrams in your Markdown files with Mermaid

#122

Post by laurent123456 »

Ciph wrote: post #107
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.

This is a known issue which hopefully should be fixed soon: https://github.com/laurent22/joplin/issues/6074

Re: Include diagrams in your Markdown files with Mermaid

#123

Post by schemescape »

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 support nearly as many diagram types as Mermaid).

Re: Include diagrams in your Markdown files with Mermaid

#124

Post by [deleted] »

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…

[deleted]

Re: Include diagrams in your Markdown files with Mermaid

#125

Post by enzanki_ars »

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/#/

ASCIIFlow is less accessible than Mermaid though for folks that use screen readers. Mermaid can be read as is from the source, or be transformed into a readable format for screen readers, but ASCIIFlow has no such mechanism to translate it into a format that can be accessible.

Re: Include diagrams in your Markdown files with Mermaid

#126

Post by julienb_sea »

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.

To be fair, I'm not sure "offline readability" is an actual problem anymore. VS Code and (presumably) other IDEs offer a very simple live-preview window for viewing and editing markdown files.

Re: Include diagrams in your Markdown files with Mermaid

#127

Post by gavingmiller »

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

3 is hardly a sea shanty of vulnerabilities for a 7 year old library. I think you're conflating releases with vulns.

Re: Include diagrams in your Markdown files with Mermaid

#128

Post by tomrod »

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.

I'm getting vibes of "MOISTURIZE ME" from Doctor Who.

Re: Include diagrams in your Markdown files with Mermaid

#129

Post by tasty_freeze »

raman162 wrote: post #50
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.

One thing that might help is using ":set virtualedit=all". This makes all lines act as if there are unlimited spaces at the end of line. That means you can move anywhere on the screen by cursor or by clicking with your mouse, etc, and not have to worry about typing in all the padding yourself. Once you place a character at column N, it will insert spaces up to column N-1 then place the new character.
Post reply on HN