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

261–270 of 272 posts

Re: Include diagrams in your Markdown files with Mermaid

#261

Post by [deleted] »

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…

[deleted]

Re: Include diagrams in your Markdown files with Mermaid

#262

Post by raman162 »

tasty_freeze wrote: post #129
raman162 wrote: post #50

Earlier quoted context omitted.

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.

This is cool, didn't know about that, will try that out next time.

Re: Include diagrams in your Markdown files with Mermaid

#263

Post by riffic »

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.

I've seen Excalidraw mentioned quite a few times, you've just given me a nudge to go check it out. Thanks for the plug.

Re: Include diagrams in your Markdown files with Mermaid

#264

Post by avgcorrection »

PinguTS wrote: post #232
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…

We should not forget, that the "spirit of Markdown" is: > 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). Inventor of Markdown https://daringfireball.net/projects/markdown/

You’re at least the third person to point to that paragraph while failing to acknowledge an important paragraph further into the article. :)

> 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.

So a text-to-HTML conversion to with the overriding design goal of being readable as-is… that’s the Gruberian spirit, and the basis for my original post.

Re: Include diagrams in your Markdown files with Mermaid

#265

Post by avgcorrection »

jasonlotito wrote: post #151
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…

ASCII-art is generally difficult to write as denoted by the numerous tools that have been created to generate ASCII-art for markdown. ASCII-art is also much more difficult to edit after the fact. The spirit of Markdown is succinctly described on DF's Markdown project website. "Markdown allows you to write using an easy-to-read, easy-to-write plain text format." Mermaid makes it easy-to-read and easy-to-write. ASCII i…

> The spirit of Markdown is succinctly described on DF's Markdown project website.

> "Markdown allows you to write using an easy-to-read, easy-to-write plain text format."

The third/fourth person to quote the original article while failing to acknowledge this paragraph from the same article:

> 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.

Your quote brings up two things that might be in conflict sometimes:

1. Being easy to write

2. Being easy to read

Given that the “overriding design goal” (my emphasis) is to be as “readable as possible”, it immediately follows that (2) takes precedence over (1). Which is why you assertion here:

> While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art.

Misses the point—the original spirit is to be easy to read, and that does (by implication) take precedence over being easy to write.

Re: Include diagrams in your Markdown files with Mermaid

#266

Post by Zababa »

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…

A good example of ASCII diagrams: https://github.com/fpereiro/backendlore

Re: Include diagrams in your Markdown files with Mermaid

#268

Post by adrianomartins »

michaelsbradley wrote: post #245
adrianomartins wrote: post #242

This is pretty cool, something that I'd actually use if there was a simple SaaS option for it.

GitHub? https://github.blog/2022-02-14-include-diagrams-markdown-fil...

Amazing! This is awesome news. Infinity useful.

Re: Include diagrams in your Markdown files with Mermaid

#269

Post by laumars »

Jtsummers wrote: post #249
laumars wrote: post #217

Earlier quoted context omitted.

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

Are you sure about this part: > The rendering stuff came later Here is the original announcement I was able to track down: http://www.aaronsw.com/weblog/001189 > For months I’ve been working with John Gruber on a new project. The idea was to make writing simple web pages, and especially weblog entries, as easy as writing an email, by allowing you to use much the same syntax and converting it automatically into HTML.…

Markdown is based on a really old nerd convention of stylising plain text. Things like /italics/ and *bold* predate MD by great many years. I was using some of markdown’s semantics even in the 90s.

This is what Aaron meant when he said:

> as easy as writing an email, by allowing you to use much the same syntax

…in that link you’ve posted.

Heck, even that quote token I used above (the greater than prefix) is a really old convention used in emails since probably before Aaron was even born.

It’s also worth noting that when markdown was released there were plenty of other plain text mark ups around (there’s some not even mentioned in that blog post too) but both Greg and Aaron point out that markdown is more readable in plain text and that’s a key decision behind it.

Re: Include diagrams in your Markdown files with Mermaid

#270

Post by cerved »

WastingMyTime89 wrote: post #255
cerved wrote: post #184

Earlier quoted context omitted.

My vanilla vim on ssh begs to differ. Offline readability matters

To you it does but manifestly your use case doesn’t matter to the people writing these pieces of software and these readme files. They care about their audience which want different things than you. At some point you can’t expect the world to cater for you. You have to deal with the annoyances which come with doing things differently or move on with your time.

the world runs on ssh terminals so I'd argue it does matter
Post reply on HN