How do I embed markdown mermaid.js diagrams?

[fire]

How do I embed markdown mermaid.js diagrams? I want to embed a diagram like: https://github.com/V-Sekai/manuals/issues/460

[cderv]

You should start by the documentation part about Diagrams in Quarto: https://quarto.org/docs/authoring/diagrams.html

Did you already give it go and is something not clear enough ?

[AleksandarMedarevic]

Dear cderv, I have a similar question. I have created diagram in Quart and Mermaid. After rendering it provides really simple and clear plot. However, after I upload it on GitHub and using GitHubPages, I see only code chunk. I trey to solve a problem. Probably it should be somethin in yamal file, bit without success. Could you please give me some hint. Aleksandar

[cderv]

Please do post a new question in Discussion with an example (or a link to a repo) and we could probably help you ! Thanks

[fire]

The {mermaid} tag is incompatible with mermaid tag on Github.

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

Loading

[fire]

You are correct.

You're saying my workflow only works when quarto is expecting a Quarto document with Quarto syntax.

I wasn't aware of this difference. So I was confused.

I'll have more time to review your instruction by tomorrow.

[fire]

I was expecting things the default syntax for .md to be github markdown.

[fire]

To restate: I was expecting the default syntax for .md to be GitHub markdown in quatro. Therefore when I put the GitHub syntax for Mermaid it failed. This is a Quatro project so using .qmd and the GitHub markdown syntax would resolve adding mermaid diagrams.

[cderv]

Quarto Markdown syntax is based on Pandoc's Markdown syntax + some addition. We says in https://quarto.org/docs/authoring/markdown-basics.html

Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax. Pandoc markdown is an extended and slightly revised version of John Gruber’s Markdown syntax.

And we point to Pandoc's Markdown reference.

This is a different syntax than Github Flavored Markdown, and GFM is an output that you can produce using a .qmd file https://quarto.org/docs/output-formats/gfm.html . This means you can write Pandoc's Markdown, and get a compatible Github Document.

Regarding the mermaid feature, Github has introduced the feature in the HTML previewer to know what to do with mermaid code chunks. They use the source code chunk syntax.
In quarto, computation code are with computation engine, and we provide a mermaid computation that we'll know what to do according to the output chosen. (e.g. for HTML it will create the HTML code and also add in the document all the CSS and JS required).

If you want quarto render to know what to do with your mermaid chunks, it needs to follow Quarto expected syntax. As you start from a GFM document, you need somehow to convert some syntax. I think you should not have much to convert and this mermaid thing could be the only thing.
A simple approach could be regex preprocessing to replace ```mermaid by ```{mermaid} ), but if you find you need to convert more syntax then you could use pandoc directly to convert from gfm to Pandoc's markdown.

Hopefully this clarifies better the context and give you ideas.

[workplacebot]

Thank you both for taking the time to discuss this topic.