Various mermaid rendering issues

[rcannood]

Bug description

Throughout the different releases, there have been various rendering issues with Mermaid in Quarto. I understand that there's a lot of moving parts to keep track of, so no judgement there.

I just noticed a new one with Quarto 1.3, so I thought I'd do a more thorough investigation. I created this repo which gets rendered to this site, which should be a mirror of the mermaidjs syntax documentation.

Since Quarto 1.3 uses mermaid 9.1.1, I went back to the earliest version of mermaid js which had the syntax examples in the docs, which happened to be version 9.3.0. I used this script to translate the md files in the mermaid repository to qmd files in my repository.

Issues in Quarto v1.3

(See comment below for issues in Quarto v1.4, since some issues have already been fixed by upgrading to mermaid 10)

Update: issues that have already been solved in Quarto v1.4 have been ticked!

Flow charts:

• No background for text on links makes the labels less readable. Example, Expected
• Character escaping doesn't work. Example, Expected
• ❗ ❗ Backgrounds of subgraphs in the Flowchart makes the chart unreadable (also in dark mode). Example, Expected

• Interactive tooltips don't work. Example, Expected.
• Html code is not escaped - similar to previously mentioned escaping issues. Example, Expected
• Fontawesome icons are not rendered. Example, Expected

Sequence diagrams:

• Background and labels is rendered behind vertical line, resulting in less readability. Example, Expected.

Class diagrams:

• Generics are not rendered properly. Example, Expected
• Html code in labels. Example, Expected
• Background in concurrency diagram is coloured wrong. Example Expected

This was all rendered with quarto 1.3.340.

Output of quarto check

[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.1: OK
      Dart Sass version 1.55.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.3.340
      Path: /home/rcannood/opt/quarto-1.3.340/bin

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.11.3
      Path: /usr/bin/python3
      Jupyter: 5.2.0
      Kernels: python3, julia-1.7, ir

(/) Checking Jupyter engine render....0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
0.00s - Debugger warning: It seems that frozen modules are being used, which may
0.00s - make the debugger miss breakpoints. Please pass -Xfrozen_modules=off
0.00s - to python to disable frozen modules.
0.00s - Note: Debugging will proceed. Set PYDEVD_DISABLE_FILE_VALIDATION=1 to disable this validation.
[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
      Version: 4.2.3
      Path: /usr/lib64/R
      LibPaths:
        - /home/rcannood/R/x86_64-redhat-linux-gnu-library/4.2
        - /usr/local/lib/R/library
        - /usr/lib64/R/library
        - /usr/share/R/library
      knitr: 1.42
      rmarkdown: 2.20

[✓] Checking Knitr engine render......OK

Checklist

• Please include a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• Please format your issue so it is easier for us to read the bug report.
• Please document the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• Please document the operating system you're running. If on Linux, please provide the specific distribution.
• Please provide the output of quarto check so we know which version of quarto and its dependencies you're running.

[rcannood]

Additional questions:

• If desirable, these issues can be converted into separate github issues.

• Some of these examples could be included in the guide on the quarto website. WDYT?

[mcanouil]

Thanks for this pretty comprehensive report, it will help a lot.

No worries, if needed, it's easy for maintainers to turn this list items into list of issues, which would turn this one into an "epic".

[cscheid]

Thanks for the report, @rcannood . I hate to do this to you, but could you please check these issues on the latest 1.4 version? We just upgraded to mermaid 10 and I expect a number of these problems as well. The issue is that I don't know what you expect the output to be (since I'm not a mermaid user), so I could use help there: https://github.com/quarto-dev/quarto-cli/releases/tag/v1.4.36

[rcannood]

I added a CI script, regenerated the /syntax/*.qmd files using the mermaid v10.1.0 release, and bumped the quarto version used by the CI to 1.4.36, resulting in this website render.

The issue is that I don't know what you expect the output to be

That's why I copied the diagrams that are already part of mermaid.js.org. That way, you can compare the output of the same figures rendered using quarto 1.4.36 and the official mermaid.js documentation side by side. For each of the items listed above and below, I provided a link to the section rendered by quarto where the issue occurs, and the expected output as rendered at mermaid.js.org.

Quarto 1.4.34

Some problems seem to have been fixed, others still persist:

Flow charts:

• ❗ ❗ Backgrounds of subgraphs in the Flowchart makes the chart unreadable (also in dark mode). Example, Expected

• Interactive tooltips don't work. Example, Expected.

• Fontawesome icons are not rendered. Example, Expected

Sequence diagrams:

• Background and labels is rendered behind vertical line, resulting in less readability. Example, Expected.

State diagram:

• Background in concurrency diagram is coloured wrong. Example Expected

[rcannood]

TBH most of the remaining issues are nice-to-haves, except for the backgrounds of subgraphs in flow charts (and the concurrency view in the state diagrams) are quite.

If the background issue could be fixed in quarto 1.3, that'd be fantastic, because it is something that used to work in quarto 1.2 and earlier ☺️

[rcannood]

The reason why it'd be fantastic if the fix for the subgraph background fills could still be included in v1.3 is because it used to work fine with Quarto v1.2. We just updated one of our sites (openproblems-bio/website) to Quarto v1.3 to get access to some other bug fixes, but it seems some diagrams were broken in the process.

We can always add a workaround to our CSS, but I can imagine other people might also encounter the same issue when upgrading from v1.2 to v1.3.

At any rate, I'm already happy if we do manage to find a bug fix, even if it's included in v1.4 only.

[jmcvw]

Ok if I add another bug to this list? I can start a new issue if you prefer, but this seems like a nice catch-all.

I am currently using Quarto 1.4.58, but I installed back to 1.4.37 to see when this first occurs - there was no problem with 1.3.

If I try to render to png usng the YAML

---
title: "Untitled"
format:
  html:
    mermaid-format: png
---

```{mermaid}
flowchart LR
A --> B
```

I get the error:

ERROR: TypeError: Relative import path "puppeteer/mod.ts" not prefixed with / or ./ or ../

TypeError: Relative import path "puppeteer/mod.ts" not prefixed with / or ./ or ../
    at async getPuppeteer (file:///Applications/quarto/bin/quarto.js:35208:24)
    at async fetcher (file:///Applications/quarto/bin/quarto.js:35337:22)
    at async getBrowserExecutablePath (file:///Applications/quarto/bin/quarto.js:35341:28)
    at async criClient (file:///Applications/quarto/bin/quarto.js:35727:28)
    at async file:///Applications/quarto/bin/quarto.js:35710:22
    at async Semaphore.runExclusive (file:///Applications/quarto/bin/quarto.js:35394:29)
    at async Object.createPngsFromHtml (file:///Applications/quarto/bin/quarto.js:35891:44)
    at async makePng (file:///Applications/quarto/bin/quarto.js:63036:72)
    at async Object.cell (file:///Applications/quarto/bin/quarto.js:63101:20)
    at async Promise.all (index 0)

If you remove the png line, it renders, but all the base text is blue, whereas it used to be black - don't know if that is intended, but it is different than I expected

---

quarto check output

[✓] Checking versions of quarto binary dependencies...
Pandoc version 3.1.2: OK
Dart Sass version 1.55.0: OK
NOTE: Deno version 1.33.2 is too old. Please upgrade to 1.33.1 or later.
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
Version: 1.4.58
Path: /Applications/quarto/bin

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
Version: 3.9.13 (Conda)
Path: /usr/local/anaconda3/bin/python
Jupyter: 4.11.1
Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........OK
Version: 4.3.0
Path: /Library/Frameworks/R.framework/Resources
LibPaths:
- /Library/Frameworks/R.framework/Versions/4.3-x86_64/Resources/library
knitr: 1.42
rmarkdown: 2.21

[✓] Checking Knitr engine render......OK

[davidwilby]

At least one of these issues was not present 3 months ago, specifically:

Fontawesome icons are not rendered.

I have a revealjs slide deck rendered by quarto (https://github.com/davidwilby/ResearchSoftwareMethods) in which FontAwesome icons were rendered correctly in a mermaidjs flowchart.

The slides were rendered on GitHub actions using quarto but unfortunately I don't know exactly which version as the runner logs have expired, but this shows that this feature was working correctly in a previous version of quarto.

[cscheid]

At least one of these issues was not present 3 months ago, specifically:

We are aware, that's why this issue is open.

The slides were rendered on GitHub actions using quarto but unfortunately I don't know exactly which version

You can inspect the generated HTML output's meta tags for that information.

[ForBo7]

Is there any timeline when we could expect Mermaid rendering to be fixed? My site uses Quarto 1.4.294 — in hindsight, I probably shouldn't have moved to 1.4 yet as it's prerelease heh.

[erikaduan]

Rendering of mermaid diagrams from Quarto notebooks into the gfm (GitHub flavoured markdown) output is currently producing errors.

For example, the following mermaid code chunk renders nicely when I click render from the RStudio IDE.

flowchart LR

A("Clean and 
analyse data") --> B("Draft report")  

B --> C("Change report parameters,
update data or
fix mistakes")

C -. Rerun code .-> A

However, when I navigate to my github markdown document, the following error message is displayed instead of a diagram.

It is possible that GitHub is already aware of this issue as their help page contains the statement:

Note: You may observe errors if you run a third-party Mermaid plugin when using Mermaid syntax on GitHub.

My Quarto notebook global code chunk options are also listed below.

---
execute:
  echo: true
  output: true
  message: false
  warning: false

format:
  gfm:
    toc: true
---

[ForBo7]

I installed 1.4.315, previewed my site locally, and I'm still having the same rendering issues.

flowchart LR
  subgraph A [Layer 1]
    direction LR
    id1[Affine Function] --> id2[ReLU]
  end

  subgraph B [Layer 2]
    direction LR
    id2 --> id3[Affine Function]
  end
  
  subgraph C [Loss Function]
    direction LR
    id3 --> id4[MSE]
  end

[mcanouil]

There is confusing post here.

#5319 fixed an issue regarding GFM, not the background issue referenced here.

@ForBo7 Showing only mermaid code is not helpful as it does not show format, etc.

[mcanouil]

@rcannood We'll just hide the comments as "off topic".

[ForBo7]

There is confusing post here.

#5319 fixed an issue regarding GFM, not the background issue referenced here.

@ForBo7 Showing only mermaid code is not helpful as it does not show format, etc.

I'm not using any formatting or additional config/theming files or anything of the sort. When I write my Mermaid Diagram, Quarto renders it like that, instead of correctly rendering it like the following.

flowchart LR
  subgraph A [Layer 1]
    direction LR
    id1[Affine Function] --> id2[ReLU]
  end

  subgraph B [Layer 2]
    direction LR
    id2 --> id3[Affine Function]
  end
  
  subgraph C [Loss Function]
    direction LR
    id3 --> id4[MSE]
  end

Loading

Let me know if you would like any other piece of information in particular that would help narrow down the issue.

[rcannood]

Just to verify, I updated the test website containing all mermaidjs documentation to quarto 1.4.322, and I can still reproduce each of the previously mentioned issues.

I hope that each of the issues become apparent by clicking 'Example' and comparing to 'Expected'. Please let me know if something is not clear.

Quarto 1.4.322

Flow charts:

• ❗ ❗ Backgrounds of subgraphs in the Flowchart makes the chart unreadable (also in dark mode). Example, Expected

• Interactive tooltips don't work. Example, Expected.

• Fontawesome icons are not rendered. Example, Expected

Sequence diagrams:

• Background and labels is rendered behind vertical line, resulting in less readability. Example, Expected.

State diagram:

• Background in concurrency diagram is coloured wrong. Example Expected

[catanzaromj]

In case anyone comes across this trying to change the dark background in a subgraph, here's a fix.

Modify the variable mermaid-fg-color--lightest in your CSS/SCSS and it will update the subgraph background. For example, to set it to white:

/*-- scss:defaults --*/
//other stuff
$mermaid-fg-color--lightest:#FFFFFF;

In case it helps anyone debug this, this line sets the subgraph background color to mermaid-fg-color--lightest, since subgraphs are cluster elements. This defaults to $mermaid-fg-color--lightest: lighten($body-color, 20%); according to the docs. Should it default to a background color instead of a foreground color?

[cscheid]

@catanzaromj We'd have to test that with a number of mermaid charts to be sure, but I think you're right and it was a typo when I wrote that. Can you open a new issue? Thanks.

[NiccoMlt]

Hi, not sure if this is the right issue, but before opening a new one I try here.

Last week I noticed that in a Reaveal.js presentations written in Quarto, the Mermaid diagrams rendered correctly while on browser, but when generating a PDF with Decktape the boxes had a wrong size and the text overlapped with the border:

Initially I though that the problem was on the Decktape side, and I opened astefanutti/decktape#328, but after that I discovered that the same problem happens with RStudio:

I'm using Quarto 1.4.553 with RStudio 26.2.4

See https://github.com/NiccoMlt/quarto-mermaid-decktape-issue-demo for a working example of the problem

[cscheid]

I imagine that if you use decktape and revealjs outside of quarto you'll see the same problem (so this isn't something Quarto can do. And while we try not to break decktape, it's not something we officially support either.)

The problem is likely that decktape is confusing mermaid's window size determination code. You'll need to generate the mermaid graphics at rendering time: https://quarto.org/docs/authoring/diagrams.html#mermaid-formats

[NiccoMlt]

Yes, initially I assumed it was something decktape-related because it worked like a charm in any browser, but when I also saw the problem on RStudio's own preview I thought it might be something related to the code that was output by Quarto.
Still, it makes sense that it's not the case and RStudio preview panel just messes up with the window size in a similar way decktape does.

Thank you for your suggestion by the way, I'll give it a try tonight and see if it can serve as a workaround

[NiccoMlt]

I confirm that using mermaid-format: png works as a workaround, thanks 👍🏻

Sadly, using SVG format (instead of PNG) still presents some problems:

in this case, the problem can be experienced even with browser and not only inside RStudio o with decktape:

It seems to be rendered too widely, because adding a magic comment to force the figure to use the 100% of the available width (%%| fig-width: 100%) fixes the problem for the SVGs

[jorishijmans]

While rendering the mermaid diagram (i.e. timeline) in html is possible, previewing results in error: "undefined"

Tested with Quarto v1.4.554 in VS Code on Windows (see ### context for more info)

timeline
    title MermaidChart 2023 Timeline
    section 2023 Q1 <br> Release Personal Tier
       Bullet 1 : sub-point 1a : sub-point 1b
                : sub-point 1c
       Bullet 2 : sub-point 2a : sub-point 2b
    section 2023 Q2 <br> Release XYZ Tier
       Bullet 3 : sub-point <br> 3a : sub-point 3b
                : sub-point 3c
            Bullet 4 : sub-point 4a : sub-point 4b

Rendering in html produces:

Context

Quarto v1.4.554 on Windows 11

VS Code

Version: 1.89.1 (user setup)
Date: 2024-05-07T05:13:33.891Z
Electron: 28.2.8
ElectronBuildId: 27744544
Chromium: 120.0.6099.291
Node.js: 18.18.2
V8: 12.0.267.19-electron.0
OS: Windows_NT x64 10.0.22631

Google Chrome

Versie 125.0.6422.61 (Officiële build) (64-bits)

[rcannood]

Hi @cscheid !

First of all, I'd like to apologize. I didn't intend for this GitHub issue to become a catch-all for any mermaid-related issues in quarto.

I just updated the demo website ( https://mermaid-demos-in-quarto.netlify.app/ ) to quarto 1.5.54 and mermaid 10.2.4. In comparison to my original post, a lot of problems have been fixed, and some still persist.

Would it make sense to close this GitHub issue and for me to create issues for each of the (smaller) remaining issues? In this way, the issue itself is less daunting and other (unrelated) issues do not get added onto this one. No offence to anyone who added other issues to this one, I just think that your issue will get solved quicker if you create a separate issue for it.

Let me know what you think :)

[cscheid]

Yes, please. Two features of good issues are:

• they reference recent versions
• they are specific

Both of these make it easy for us to get to the bottom of it.

[rcannood]

Sounds good!

I added a comment or created new issues for the most important problems.

• Mermaid subgraph background too dark #9178 (comment)
• [mermaid] fontawesome icons are not rendered #10303
• [mermaid] text not legible in dark mode #10304

When these are fixed, I'll update the mermaid-demos-in-quarto page and cross-check for additional issues.

Happy for this issue to be closed in favour of #9178, #10303 and #10304!