Render mermaid diagrams directly in markdown

[yoshutch]

Description

Ask

I understand that in order to render diagrams into a PDF/Docx file, you are supposed to use .qmd files with a {} block to indicate compution is needed to render the diagrams in order to produce an image.

I would like to propose that (at least mermaid) diagrams be rendered without these requirements. That is, when Quarto sees ```mermaid in a native markdown file (.md extension), it automatically identifies and renders it as the mermaid diagram instead of a block of code. GitHub and JetBrains IDEs do this.

Essentially I want both GitHub and Quarto to use a single file as its source and display the same rendered mermaid diagram(s).

Reasoning

Most of my work involves architectural documents containing diagrams alongside text. I store these documents in GitHub for various reasons. The audience for these documents may include non-GitHub users, so I use Quarto to render PDF or Docx files to deliver to them. But with the current requirements, I have to store my markdown files as .qmd files with the ```{mermaid} code block directives in order for Quarto to render the diagrams in the PDF/Docx files. When I upload the .qmd files, GitHub does not recognize the .qmd extension and therefore does not render the markdown nor the diagrams on them. JetBrains IDEs (like IntelliJ) also do not recognize the file extension and therefore don't render the markdown. When I configure my IDE to render these files like markdown files, it does just the normal markdown rendering but does not recognize the ```{mermaid} directive and only renders it as a code block in the markdown preview.

Alternatives

• I don't want to have two copies of my markdown files (one .md extension with ```mermaid directives, and the second .qmd extension with ```{mermaid} directives) as that introduces confusion and risk of getting documentation out-of-sync.

• I don't want to upload the PDF/Docx files to GitHub since they're not viewable, nor easily parsable with the diffing tools.

• Saving a copy of the diagram images and inserting them into the markdown or .qmd files defeats the purpose of storing diagrams as code in mermaid format.

• I've tried writing a script that creates temporary .qmd files for each .md file, replacing the code block directives, then having Quarto render those, then delete the temporary files after. But this felt like extra steps for what I had initially assumed was baked into the Quarto tool/CLI. (when I tried this, I ran into the same issue on WSL with Quarto failing to use chrome-headless-shell as Bug when building a PDF document containing Mermaid graph using Gitlab CI #14166 and began searching for another way to render my mermaid diagrams, hence partly why I am proposing this feature).

Other

• Related to Mermaid Diagram Rendering Support in .md files #14025

In the linked discussion it was mentioned:

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 get the desire to not break current usage patterns. To me the ```mermaid code block directive is intended to be rendered as a diagram, if I wanted to just display the code snippet of the mermaid diagram then I wouldn't put the mermaid directive at the top of the code block. Now that may not be everyone's opinion and that's fine. Might I suggest an environment variable that turns on or off this kind of rendering (e.g. QUARTO_RENDER_DIAGRAMS_WITHOUT_COMPUTATION=true)?

[cscheid]

I would like to propose that (at least mermaid) diagrams be rendered without these requirements. That is, when Quarto sees ```mermaid in a native markdown file (.md extension), it automatically identifies and renders it as the mermaid diagram instead of a block of code. GitHub and JetBrains IDEs do this.

Sorry to be blunt about it, but we're not going to do this. (You're welcome to do it yourself with a Lua filter that catches the appropriate classes and renders them yourself!)

But Quarto has a strong convention of the presence of curly braces indicating "execution behavior" and lack of braces indicating classes in the AST node. This would break that convention in a non-productive way for our existing users, our documentation, and our tooling.

[mcanouil]

Here is a lua filter for this: https://github.com/mcanouil/quarto-issues-experiments/blob/main/lua-filters/strip-mermaid-braces.lua

--- Strip Mermaid Braces - Filter
--- @module "strip-mermaid-braces"
--- @license MIT
--- @copyright 2026 Mickaël Canouil
--- @author Mickaël Canouil
--- @version 0.1.0
--- @brief Rewrite executable Mermaid cells as plain Mermaid fences for GFM output.
--- @description Quarto Lua filter that converts executable Mermaid code cells
--- (```{mermaid}) into plain Mermaid fenced code blocks (```mermaid) when the
--- output format is a GFM or CommonMark variant, so GitHub renders the
--- diagrams natively.

--- Test whether the current Quarto output format is a GFM/CommonMark variant.
--- @return boolean true when the format is gfm, commonmark, or markdown_strict
local function is_gfm_variant()
  return quarto.doc.is_format('gfm')
      or quarto.doc.is_format('commonmark')
      or quarto.doc.is_format('markdown_strict')
end

--- Rewrite ```{mermaid} cells as plain ```mermaid fences for GFM-like formats.
--- @param el pandoc.CodeBlock the code block to inspect
--- @return pandoc.RawBlock|nil a RawBlock with the rewritten fence, or nil
local function CodeBlock(el)
  if not is_gfm_variant() then return nil end
  if not el.classes:includes('{mermaid}') then return nil end
  return pandoc.RawBlock('markdown', '```mermaid\n' .. el.text .. '\n```')
end

return {
  { CodeBlock = CodeBlock }
}

[cscheid]

I think the original request was to go in the opposite direction, taking ```mermaid blocks and producing diagrams from them.

[mcanouil]

The idea was to have the "single source of truth" be a valid Quarto document that generates the markdown for GitHub thus avoiding the "out-of-sync" issue.

[yoshutch]

My intent was to have regular GitHub flavored Markdown as the "source of truth" but still have the ability to use Quarto to render the diagrams as if it were looking at quarto files with the execution behavior. Thanks for the idea here.