Include diagrams in your Markdown files with Mermaid • Hacker News Board

Re: Include diagrams in your Markdown files with Mermaid

#21

Post by e12e » Mon, Feb 14, 2022, 6:22 PM UTC

qbasic_forever wrote: post #13

timwis wrote: post #9

I’m super excited for this! One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md: ```js const foo = 1 + 1 ``` Rendered as: `2` ? Isn’t that kind of what we’re doing here with the mermaid source tag? That tag is for showing source code, no? Feels like there should be another tag for rendering it.

Only the mermaid identifier is supported for triple backticks blocks, you can't put js and have it spit out script that executes in the browser.

I think op meant that we can:

   ```ruby
   # syntax highlighted as ruby
   a = 1 + 1
   ```

And:

   ```js
   // syntax highlighted as js
   a = 1 + 1
   ```

So maybe we should have something like a "bang" prefix to evaluate and inline/embed like:

   ```!ruby
   # evaluated 
 as ruby
   a = 1 + 1
   # renders 2 because of implicit return? 
   ```

Re: Include diagrams in your Markdown files with Mermaid

#22

Post by reificator » Mon, Feb 14, 2022, 6:22 PM UTC

qbasic_forever wrote: post #13

timwis wrote: post #9

I’m super excited for this! One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md: ```js const foo = 1 + 1 ``` Rendered as: `2` ? Isn’t that kind of what we’re doing here with the mermaid source tag? That tag is for showing source code, no? Feels like there should be another tag for rendering it.

Only the mermaid identifier is supported for triple backticks blocks, you can't put js and have it spit out script that executes in the browser.

Which is the exact inconsistency under scrutiny here.

Re: Include diagrams in your Markdown files with Mermaid

#23

Post by limmeau » Mon, Feb 14, 2022, 6:22 PM UTC

floodle wrote: post #12

I'm curious why they went for mermaid rather then GraphViz. Can anybody comment?

Mermaid has explicit support for diagrams that look UML-ish (never mind the filled triangle arrowheads for inheritance): class, state and sequence diagrams. Graphviz doesn't do that easily.

Re: Include diagrams in your Markdown files with Mermaid

#24

Post by qbasic_forever » Mon, Feb 14, 2022, 6:25 PM UTC

tehbeard wrote: post #19

qbasic_forever wrote: post #13

Earlier quoted context omitted.

Only the mermaid identifier is supported for triple backticks blocks, you can't put js and have it spit out script that executes in the browser.

You missed the point, that being; isn't triple backticks meant for whitespace preserving, highlighted in certain cases source code? And not embedding other file types.

No there's not a formal requirement or spec for how markdown blocks are rendered. Even things like syntax highlighting are optional choices different renderers make (and even the whole idea of highlighting is not specified or defined, how do you define the grammer, etc?).

Some tools in the computational notebook space use markdown with fenced code blocks as blocks of executable code, see for example jupytext: https://github.com/mwouts/jupytext/blob/main/docs/formats.md or myst markdown: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h... or nbconvert: https://nbconvert.readthedocs.io/en/latest/

Re: Include diagrams in your Markdown files with Mermaid

#25

Post by lelandbatey » Mon, Feb 14, 2022, 6:26 PM UTC

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

Something to know is that sequencediagram.org seems to be just a website skin around PlantUML Sequence Diagrams[0]. PlantUML is open source and is ultimately built on top of Graphviz as well.

Another nice thing is that PlantUML is supported (alongside Mermaid) in GitLab, and has been supported for at least two years. You can embed PlantUML diagrams into your README without committing any images to the repo or linking to external images, just like Mermaid.[1]

[0] - https://plantuml.com/sequence-diagram

[1] - https://docs.gitlab.com/ee/administration/integration/plantu...

Re: Include diagrams in your Markdown files with Mermaid

#26

Post by lelandbatey » Mon, Feb 14, 2022, 6:28 PM UTC

WalterGR wrote: post #14

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.

Has Graphviz been re-implemented in JavaScript or compiled to WASM?

Other services, such as Gitlab[0], allow you to embed Graphviz & PlantUML into a README just like (and alongside) Mermaid, but the images are rendered server-side.

[0] - https://docs.gitlab.com/ee/administration/integration/plantu...

Re: Include diagrams in your Markdown files with Mermaid

#27

Post by lelandbatey » Mon, Feb 14, 2022, 6:30 PM UTC

limmeau wrote: post #23

floodle wrote: post #12

I'm curious why they went for mermaid rather then GraphViz. Can anybody comment?

Mermaid has explicit support for diagrams that look UML-ish (never mind the filled triangle arrowheads for inheritance): class, state and sequence diagrams. Graphviz doesn't do that easily.

PlantUML[0], which is built on top of Graphviz, does have support for UML and other services such as Gitlab do support direct embedding of PlantUML (which also means you can embed Graphviz, since PlantUML is an extension of Graphviz).

[0] - https://plantuml.com/object-diagram

Re: Include diagrams in your Markdown files with Mermaid

#28

Post by HNSucksAss » Mon, Feb 14, 2022, 6:33 PM UTC

No post body was provided.

Re: Include diagrams in your Markdown files with Mermaid

#29

Post by qbasic_forever » Mon, Feb 14, 2022, 6:39 PM UTC

reificator wrote: post #22

qbasic_forever wrote: post #13

Earlier quoted context omitted.

Only the mermaid identifier is supported for triple backticks blocks, you can't put js and have it spit out script that executes in the browser.

Which is the exact inconsistency under scrutiny here.

Markdown supports arbitrary HTML, you can do this:

    # Heading

    
    const foo = 1 + 1;
    window.alert(`1 + 1 = ${foo}`);
    

    Paragraphs of exposition.

In practice most markdown renderers will strip HTML or at least script tags as it is obviously a cross site security risk to allow github.com to serve user uploaded scripts without sanitization.

Re: Include diagrams in your Markdown files with Mermaid

#30

Post by ghostoftiber » Mon, Feb 14, 2022, 6:49 PM UTC

I want a lucidchart or drawio style support for mermaid. There's plugins to let them render mermaid.md files but I haven't seen anything which just lets me draw arrows between shapes and label things. Someone please make this happen, I will be forever grateful.