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

211–220 of 272 posts

Re: Include diagrams in your Markdown files with Mermaid

#211

Post by encryptluks2 »

armchairhacker wrote: post #144
julienb_sea wrote: post #126

Earlier quoted context omitted.

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.

We need to go back to something like Word documents. We’ve come full circle

How so? Word Documents are not made to be edited by hand. They are meant to be edited in Word. Markdown even with Mermaid is still readable and editable by hand. While I can agree Mermaid isn't my ideal markup, there are alternatives and you can even propose your own.

Re: Include diagrams in your Markdown files with Mermaid

#213

Post by theshrike79 »

chrisweekly wrote: post #195
riffic wrote: post #78

if you use Obsidian, Mermaid is supported natively.

Yeah, IMHO Obsidian is in a class of its own for markdown-based PKM / TFT / devnotes. And the Excalidraw plugin for Obsidian is absolutely phenomenal.

Obsidian's "a vault is just a directory structure with markdown files" is the biggest reason I use it.

Re: Include diagrams in your Markdown files with Mermaid

#215

Post by porker »

Am I the only person who thinks Mermaid output is visually unappealing?

We tried to use it for flowcharts in our documentation and its layout wasn't right. I'm assuming it uses a force directed layout system.

We switched to creating diagrams in Excalidraw and everyone is happy.

Re: Include diagrams in your Markdown files with Mermaid

#216

Post by laumars »

julienb_sea wrote: post #126
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.

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.

Yes. The main use case I have for markdown is:

* reading documents in the terminal (like man pages)

* note taking

In both those instances the less auto-formatting that the editor does the easier it is for me to use the use the file format.

I’m sure you can say that editor auto-formatting isn’t an issue because people manage fine on MS Word. But the point is I want as little distractions as possible when not taking but I also want to be able to add headings and code snippets. So wrestling with an editor when it gets its formatting rules in a mess is the exact opposite of productively. Eg take a look at the number of authors that still use DOS editors for similar reasons.

Re: Include diagrams in your Markdown files with Mermaid

#217

Post by laumars »

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

Now it’s not. Markdown was intend to be legible in plain text but visually emulate rendered text. The rendering stuff came later but even then it still had an emphasis on plain text readability.

There is a reason it was chosen for README, INSTALL etc documents in project repositories that are (or, at least until relatively recently in computing history, were) traditionally read in the command line.

Re: Include diagrams in your Markdown files with Mermaid

#218

Post by laumars »

Jtsummers wrote: post #145
daptaq wrote: post #143

Earlier quoted context omitted.

The "easy-to-read [...] plain text format" indicates to me that the idea was that markdown should be readable in plaintext form too. The ability to convert it to HTML is a different goal?

Maybe? My point, though, is that from day 1 it was meant to be rendered as HTML. So what Github does with it (rendering README.md files) is perfectly compatible with that original intent. Just like everyone who used md->html renderers for their blogs or whatever other content. If you just want plaintext, then you don't need markdown or any other markup. Just a plaintext file, like, I don't know, a README file. Don't…

> Maybe? My point, though, is that from day 1 it was meant to be rendered as HTML.

No, from day 1 it was meant to be readable as plain text and optionally rendered as HTML

Nobody is disputing that a key requirement of MD is to be machine parseable. What you’re missing is that another key requirement is for it to be human readable in plain text because it needs to be readable even when it hasn’t been rendered. Ie the rendering is an optional step but the format has to support one’s choice whether to render.

Re: Include diagrams in your Markdown files with Mermaid

#219

Post by roboyoshi »

kaycebasques wrote: post #20

sequencediagram.org is a pleasant (and free) tool for generating standalone diagrams like this outside of GitHub. I discovered it while helping Corrily with their docs, e.g. the diagram at the top of this page: https://docs.corrily.com/docs/price-optimization-overview

you might also enjoy swimlanes.io

Re: Include diagrams in your Markdown files with Mermaid

#220

Post by the_gipsy »

chrismorgan wrote: post #193
gavingmiller wrote: post #127

Earlier quoted context omitted.

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

I’m not impressed with what I see of the three that there are , in some cases to do with how they came about and in some how they’ve been fixed. The most recent one, https://security.snyk.io/vuln/SNYK-JS-MERMAID-2328372 : I would be very concerned about trusting code that could be in any way adjacent to security written by whoever wrote (and whoever reviewed or committed) this original sanitizeUrl function https://gi…

> I don’t want to engage, lest I get sucked in. :-)

Was about to suggest this

Post reply on HN