Mermaid Block Diagrams not working

[prosoitos]

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

[mcanouil]

Is this supported in Mermaid.js 11.2?

[prosoitos]

Ah! Good point!!! 🙂

It is, but you have to use block-beta instead of block.

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-beta syntax.

They must have removed the beta part in the latest version.

[mcanouil]

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.)

[prosoitos]

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.

[prosoitos]

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]

@prosoitos Mermaid has been updated

• Upgrade mermaid to 11.12 #13601

I triggered a new pre-release and 1.9.9 should be the one with updated mermaid.

Hopefully that helps.

[prosoitos]

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.

[prosoitos]

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]

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.

[prosoitos]

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?