Repository navigation
Mermaid Block Diagrams not working #13614
Description
I have:
- searched the issue tracker for similar issues
- installed the latest version of Quarto CLI
- formatted my issue following the Bug Reports guide
Bug description
I am unable to include any Mermaid Block Diagrams in my Quarto documents (I am not talking about Mermaid code blocks, but the type of Mermaid diagrams called "block diagrams").
Other types of diagrams I have tested (flowcharts and sequence diagrams) do work.
Steps to reproduce
(One of the examples from the Mermaid Block Diagrams page.)
---
format: html
---
```{mermaid}
block
columns 3
a b c d
```Rendering of qmd file works without error, but instead of the diagram Mermaid inserts an image with:
Syntax error in text
mermaid version 11.6.0
Actual behavior
No response
Expected behavior
No response
Your environment
No response
Quarto check output
Quarto 1.8.25
[✓] Checking environment information...
Quarto cache location: /home/marie/.cache/quarto
[✓] Checking versions of quarto binary dependencies...
Pandoc version 3.6.3: OK
Dart Sass version 1.87.0: OK
Deno version 2.3.1: OK
Typst version 0.13.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
Version: 1.8.25
Path: /opt/quarto/bin
[✓] Checking tools....................OK
TinyTeX: (not installed)
Chromium: (not installed)
[✓] Checking LaTeX....................OK
Using: Installation From Path
Path: /usr/bin
Version: undefined
[✓] Checking Chrome Headless....................OK
Chrome: (not detected)
[✓] Checking basic markdown render....OK
[✓] Checking Python 3 installation....OK
Version: 3.13.7
Path: /usr/bin/python3
Jupyter: 5.9.1
Kernels: julia-1.12, python3
[✓] Checking Jupyter engine render....OK
Loading required package: sysfonts
(|) Checking R installation...........Loading required package: showtextdb
[✓] Checking R installation...........OK
Version: 4.5.1
Path: /usr/lib64/R
LibPaths:
- /home/marie/R/lib
- /usr/lib/R/library
knitr: 1.49
rmarkdown: 2.29
[✓] Checking Knitr engine render......OK
Activity
mcanouil commentedon Oct 25, 2025
Is this supported in Mermaid.js 11.2?
mhburle commentedon Oct 25, 2025
Ah! Good point!!! 🙂
It is, but you have to use
block-betainstead ofblock.Thanks!!! I hadn't thought of this. Mermaid has supported Block Diagrams since at least version 8.7.0 (from some quick Googling I am doing), but in early versions it was with this
block-betasyntax.They must have removed the
betapart in the latest version.mcanouil commentedon Oct 25, 2025
Then the error from Mermaid is correct.
In the future, prefer opening GitHub discussion rather than issues.
(Quarto 1.9 is likely to use 11.12.)
mhburle commentedon Oct 25, 2025
To be fair, this did look like a bug to me. The Quarto documentation does not mention which version of Mermaid is packaged with Quarto and, while it makes perfect sense that it would be behind, this hadn't occurred to me.
The Quarto Bug Reports Guide doesn't suggest to start with discussions when one suspects that there is a bug in Quarto.
I tried to follow this guide very carefully and to the best of my ability.
Anyway, thank you for your quick answer and for giving me the clue that lead me to the solution.
mhburle commentedon Oct 26, 2025
Having Quarto run an old Mermaid version makes things a little tricky because unfortunately Mermaid's website doesn't show documentation for all versions (only the latest).
This is not at all on Quarto's team of course and it is a shortcoming of the Mermaid project. But it makes it very hard to know what will work in Quarto and what won't.
Reading Mermaid change logs is not a very easy solution, so the method I have been following is trial and error, but it is very tedious.
Of course, nothing you can do about any of it. I just thought that I would mention it in hope that you might take it into account when you release Quarto versions and try to keep your Mermaid version as close to the latest as is possible.
Thank you!!!
cderv commentedon Oct 28, 2025
@prosoitos Mermaid has been updated
I triggered a new pre-release and 1.9.9 should be the one with updated mermaid.
Hopefully that helps.
mhburle commentedon Oct 28, 2025
Thank you Christophe!!!
I really appreciate it!!
It will definitely help a lot.
There is an open issue in the Mermaid repo about having documentation for all versions and maybe they'll implement it at some point, which would solve this.
mhburle commentedon Oct 28, 2025
I also don't know whether Mermaid outputs informative error messages that aren't visible when used in Quarto or whether there simply aren't any informative error messages.
I have never used Mermaid outside Quarto so I don't know its native behaviour.
In the event Mermaid does generate error messages, it would be tremendously helpful if those were displayed when used in Quarto.
As things are, when using Mermaid code from the wrong version, Quarto displays an image that at least shows the Mermaid version, but nothing else.
So it makes it hard to pinpoint which little detail of the configuration is wrong for that version (hence the lengthy trial and error).
mcanouil commentedon Oct 28, 2025
Errors are sent to the console as Mermaid is JavaScript, you should be able to see the syntax error in the console of your browser.
mhburle commentedon Oct 28, 2025
Oh great!!!! Thank you @mcanouil! This is so useful. I had no idea!
I am very JavaScript naive as you can see...
Maybe something worth mentioning in a tooltip in the Quarto Mermaid documentation for people like me who have no idea?