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

231–240 of 272 posts

Re: Include diagrams in your Markdown files with Mermaid

#231

Post by dotancohen »

encryptluks2 wrote: post #228
dotancohen wrote: post #224

Earlier quoted context omitted.

Mermaid is as readable as C++. The examples shown in the fine article are Hello, world. The information contained within would be just as clear in vulgar prose. However the Mermaid code to create complex flowcharts that are not easily described in words, would be just as opaque as the Netscape 5 codebase.

I agree that it is no ideal, at least for my tastes, but I think what you are stating is an exaggeration. If you are using reference points like someone that knows little to nothing about technology, then just about anything different that what they are used is probably as readable as C++. For example, trying to read HTML would be the same to my grandma as trying to read C++.

The whole point of Markdown is "readable by humans" in unrendered form. Mermaid breaks that.

Re: Include diagrams in your Markdown files with Mermaid

#232

Post by PinguTS »

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/

Re: Include diagrams in your Markdown files with Mermaid

#233

Post by PinguTS »

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.

Markdown has always been about "renderme". From the beginning.

If you want a simple README, then do a README and not a README.md.

Re: Include diagrams in your Markdown files with Mermaid

#234

Post by encryptluks2 »

dotancohen wrote: post #231
encryptluks2 wrote: post #228

Earlier quoted context omitted.

I agree that it is no ideal, at least for my tastes, but I think what you are stating is an exaggeration. If you are using reference points like someone that knows little to nothing about technology, then just about anything different that what they are used is probably as readable as C++. For example, trying to read HTML would be the same to my grandma as trying to read C++.

The whole point of Markdown is "readable by humans" in unrendered form. Mermaid breaks that.

Readable by humans is relative. Mermaid does not make it unreadable to some humans. Again, you are free to create an alternative that makes it more readable. Some could say that adding tables to markdown makes it unreadable. There are lot of extensions for markdown that adds features, but you have to know what they are to read them and use them. Grandma doesn't have to use Mermaid if she doesn't want to.

Re: Include diagrams in your Markdown files with Mermaid

#235

Post by Someone »

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.

The first paragraph of https://daringfireball.net/projects/markdown/:

“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).”

⇒ I think “easy to read and write” is an important, but secondary goal. The goal is to render to (X)HTML.

That’s similar to how SwiftUI’s

  struct ContentView: View {
    var body: some View {
      Text("Hello World")
    }
  }
is deemed an improvement over, for example, Java Swing’s

  JFrame frame = …
  JLabel label = new JLabel("Hello World");
  frame.getContentPane().add(label);
but in both cases, it’s the result that counts.

Re: Include diagrams in your Markdown files with Mermaid

#236

Post by tremon »

dotancohen wrote: post #227

The fine article includes this code: ```mermaid flowchart TD; A[Depoy to production] --> B{Is it Friday?}; B -- Yes --> C[Do not deploy!]; B -- No --> D[Run deploy.sh to deploy!]; C --> E[Enjoy your weekend!]; D --> E[Enjoy your weekend!]; ``` What happens if the two declarations of E conflict? E.g.: C --> E[Enjoy your weekend!]; D --> E[Have fun this weekend!];

The latter takes precedence, apparently. But the correct way to do this:

  C --> E;
  D --> E;
  E[Enjoy your weekend!];

Re: Include diagrams in your Markdown files with Mermaid

#238

Post by southerntofu »

hericium wrote: post #201

JavaScript requirement for Markdown? Page views boost through terminal-unreadable documentation? Yeah... no. I prefer ASCII drawing characters/boxes, similar to mentioned in this[1] and following comments. [1] https://news.ycombinator.com/item?id=30275327

I agree with your sentiment, although personally i like the mermaid syntax (as someone who's bad at drawing ASCII art). Are you aware of native implementations of the mermaid syntax which i could use part of my site pipeline to build SVGs/PNGs instead of rendering client-side with javascript?

Re: Include diagrams in your Markdown files with Mermaid

#239

Post by [deleted] »

Someone wrote: post #235
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.

The first paragraph of https://daringfireball.net/projects/markdown/ : “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).” ⇒ I think “easy to read and write” is an important, but secondary goal. The goal is to render to (X)HTML. That’s similar to how SwiftUI’s struct Co…

[deleted]

Re: Include diagrams in your Markdown files with Mermaid

#240

Post by zamadatix »

Someone wrote: post #235
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.

The first paragraph of https://daringfireball.net/projects/markdown/ : “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).” ⇒ I think “easy to read and write” is an important, but secondary goal. The goal is to render to (X)HTML. That’s similar to how SwiftUI’s struct Co…

From your same link it does not say un-rendered readability was a secondary goal, it says the exact opposite:

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

This also fits with the ordering from the second paragraph:

> Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.

Markdown has always included rendering capability as a goal but I think GP is right, Markdown was never intended to be an always render first format just because it included the capability to render.

Post reply on HN