Mermaid Diagram Rendering Support in .md files

[CodrinSocol]

Description

Hi there!

I need some help with configuring my Quarto project. According to the docs, Quarto only renders mermaid diagrams if placed in code blocks in .qmd files. We have two issues with this setup:

1. Markdown linters such as markdownlint do not parse .qmd file extensions (and also do IDE extensions do not recognize it)
2. Our company uses Azure DevOps for versioning and previews are not available for .qmd files. Moreover, DevOps only renders Mermaid diagrams if they are wrapped in div blocks :::mermaid <diagram> ::: instead of backticks.

Because of the aforementioned limitations, we can only use .md files, but still want to render Mermaid diagrams in a Quarto website. The outputs we are interested in are html and pdf.

What I have tried so far was to create a pre-render script that converts our desired syntax into Quarto-friendly .qmd files and configure the project to only render .qmd files. The issue with this setup is that the hot reload from quarto preview doesn't work anymore (of course, since there is no automatic sync between .md source and .qmd which Quarto watches).

Any suggestions how I can achieve a working setup with these constraints?

[mcanouil]

About markdownlint, if you are talking about the VSCode extension, there is nothing that can be done as it's a strong choice from the maintainer to not allow customisation of the files to be parsed as markdown unless Microsoft makes a change in their API to activate extensions.
The CLI on the other hand should work on qmd files.
Note that markdownlint VSCode extension is not the only Markdown linting extension.

Because {} means computation and that happens at a very early stage (+ post-processing), I don't think there is an alternative to pre-render.

[CodrinSocol]

I understand that you use {} internally for determining that a code block should be executed instead of just shown as a markdown codeblock. I was wondering whether for mermaid diagrams it would not make more sense to support rendering the diagram out of the box (i.e., with or without the {} }. As a comparison, this is default behaviour in GitHub and Markdown Preview of JetBrains IDE.

In terms of using the pre-render, it seems there is a limitation here as well. According to this and this thread, qmd files generated by the pre-render script should be added to the list of files to be rendered. But for me, the first time those qmd files are generated, Quarto does not find them.

According to the thread, this was fixed in v1.5, but Im running v1.8 and still experiencing the issue.

[mcanouil]

I understand that you use {} internally for determining that a code block should be executed instead of just shown as a markdown codeblock. I was wondering whether for mermaid diagrams it would not make more sense to support rendering the diagram out of the box (i.e., with or without the {} }. As a comparison, this is default behaviour in GitHub and Markdown Preview of JetBrains IDE.

This would be a breaking change as many users may use ```mermaid do display but not render mermaid code blocks. Although this would make things inconsistent with other diagram languages supported.
I would suggest to open a "Feature Request" discussion detailing exactly what you want, why, etc.

In terms of using the pre-render, it seems there is a limitation here as well. According to this and #7749 thread, qmd files generated by the pre-render script should be added to the list of files to be rendered. But for me, the first time those qmd files are generated, Quarto does not find them.

Without providing any means to reproduce a possible bug, I'm afraid there is no way to help.
"this" and "this" are not helpful, even GitHub doesn't like it when copy/pasting it.
Note that, GitHub automatically add descriptive text (title of the discussion/issue) when in lists.

• How pre- are pre-render scripts? #3879
• Generated .qmd file is ignored on first build #7749

Important

Accessibility: For better accessibility, please ensure link text is descriptive and meaningful rather than using generic terms such as "here". This helps all users understand the link's destination. See Writing meaningful link text (WCAG).

[CodrinSocol]

Thanks for the pointers! I have created a bug report:

• Files generated with pre-render script are not discovered in the render stage #14028