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

151–160 of 272 posts

Re: Include diagrams in your Markdown files with Mermaid

#151

Post by jasonlotito »

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 is easy-to-read, but hardly easy-to-write. While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art.

Finally, Markdown itself was designed that while the text is easy to read, Markdown itself is a conversion tool. It literally takes the text and changes it into something that is more readable. This can be seen with how Markdown handles tables. It's literally HTML table tags rather than ASCII designed tables.

This is very much in the spirit of Markdown, and things like this have already been done in the original implementation.

Re: Include diagrams in your Markdown files with Mermaid

#152

Post by avgcorrection »

Jtsummers wrote: post #138
avgcorrection wrote: post #136

Earlier quoted context omitted.

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

“A text-to-HTML conversion tool” with the “overriding design goal” of “[making] it as readable as possible”.

You wrote:

> Markdown was meant to be rendered, not left as plaintext

Then the overriding design goal would not be to make it “as readable as possible” in its “raw” form (because what would be the point of that?). So this is clearly a falsehood.

Markdown was meant to be readable as-is. Meaning that you could read it as-is or render it. At your leisure.

Also literally your words:

> was meant to be a lightweight way

With the overriding goal of making it “as readable as possible”. Keyword “override”. Which means that it takes precedence over being “lightweight”.

Then you literally wrote:

> that it wasn't meant to be rendered as HTML.

Clearly a falsehood or a strawman as I only emphasized the “overriding design goal”. Markdown was supposed to be able to be rendered as HTML… and to be readable as-is.

The part that you were wrong about was this:

> Markdown was meant to be rendered, not left as plaintext

It was designed to be readable as plaintext as well… so this assertion of yours is false since it implies that plaintext readability was not a consideration. But it was in fact the primary design goal when making the syntax.

I hope this clears things up.

Re: Include diagrams in your Markdown files with Mermaid

#153

Post by daptaq »

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.

My go-to example is uBlock: https://raw.githubusercontent.com/gorhill/uBlock/master/READ..., despite being a great add-on, has 1/3-1/2 of unlegible Markdown, that looks nice when rendered.

Re: Include diagrams in your Markdown files with Mermaid

#154

Post by daptaq »

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…

Rendering has HTML isn't really the issue, imo. The question is rather how readable the source remains, when you foget to fold lines, insert too many images without alt texts, intersperse regular HTML, etc.

Re: Include diagrams in your Markdown files with Mermaid

#155

Post by innolitics »

I really like diagrams as text for simple diagrams where you don't care too much about the formatting. I think Figma is better if you really care about the formatting. I just discovered this the other day, but you can create mermaid diagrams in Notion by adding a codeblocks and selecting the "mermaid" language from the dropdown.

Re: Include diagrams in your Markdown files with Mermaid

#156

Post by eurasiantiger »

jopsen wrote: post #149

I like the idea of mermaid.js, but why does it have to be so ugly. I don't know why, but whenever I've had a look at mermaid.js, it always made me feel like the syntax and generated diagrams were ugly. Am I the only one who thinks this? Also what's up with all the useless diagram types?

Yes, it is ugly. The layout engine doesn’t do ”these elements are kinda the same thing so place them side by side”. No hierarchy model, no constraints, everything is always placed on one axis according to order and then pretty much shifted randomly to not collide. Spiderwebs everywhere.

Also, ER diagrams are nigh unreadable due to the unusual relationship visual style used.

Re: Include diagrams in your Markdown files with Mermaid

#158

Post by lpghatguy »

jopsen wrote: post #149

I like the idea of mermaid.js, but why does it have to be so ugly. I don't know why, but whenever I've had a look at mermaid.js, it always made me feel like the syntax and generated diagrams were ugly. Am I the only one who thinks this? Also what's up with all the useless diagram types?

This is a problem I've always had with Mermaid too. Custom theming is a no-go; it's easier to make attractive diagrams with GraphViz.

I remember the docs for Mermaid.js talk about varying document trust levels, which is not something I want involved in a diagramming DSL.

Re: Include diagrams in your Markdown files with Mermaid

#159

Post by eurasiantiger »

djur wrote: post #51
jonpalmisc wrote: post #11

I think this is a good change. While I would have preferred to see support for Graphviz over Mermaid, I understand Mermaid was probably chosen for the sake of easier integration. Either way, it will be nice to be able to embed diagrams rather than constantly re-generate and re-commit images to the repo.

I believe Mermaid supports a wider range of diagram types than Graphviz. Graphviz doesn't support sequence diagrams, for instance, unless I'm missing something.

No data flow diagrams though, and that is a really big omission which other diagrams don’t cover well.

Re: Include diagrams in your Markdown files with Mermaid

#160

Post by OJFord »

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…

But Mermaid code is much more readable in plaintext than a link to an image elsewhere?

I wish they wouldn't have used code blocks though - I commented on this recently about some other plugin that was doing it: usually ``` gets syntax highlighted and 'pre' formatting, but otherwise its contents is unchanged; it's unusual to execute the contents.

    ```python
    print(42)
    ```
Renders

    print(42)
Not

    42
!

In my opinion it would've been better to use $$ as often used for mathjax, $$mermaid or something. Since it is expected that an interpretation of

    $$
    \code\here
    $$
is rendered, rather than it itself. And if we want the code itself, we have:

    ```tex
    \code\here
    ```
! How do you give an example of Mermaid code in a Readme? I'm sure they've thought of it, it can be escaped, but why? Why is it different?
Post reply on HN