Skip to content

Bump Mermaid to 11.12.0, to match CLI#986

Open
juliasilge wants to merge 4 commits into
mainfrom
chore/bump-mermaid-11-12-0
Open

Bump Mermaid to 11.12.0, to match CLI#986
juliasilge wants to merge 4 commits into
mainfrom
chore/bump-mermaid-11-12-0

Conversation

@juliasilge
Copy link
Copy Markdown
Collaborator

Fixes posit-dev/positron#13881

This PR bumps the Mermaid version used by the Diagram preview webview from 9.3.0 to 11.12.0, matching the version already bundled in the Quarto CLI.

How far behind were we?

Soooooooo far! 😱 The Diagram preview was pinned to Mermaid 9.3.0 (late 2022), while the Quarto CLI ships 11.12.0. That is two full major versions behind, plus dozens of minor releases and roughly two and a half years of drift. So a diagram could render correctly in quarto render / quarto preview (CLI) and then break in the in-editor Diagram preview, purely because the preview was running ancient Mermaid.

The user-visible symptom that surfaced this is that the newer node-shape syntax added in Mermaid 11.3.0, e.g.

flowchart TD
    A@{ shape: text, label: "This is a text block" }

renders as "undefined" in the preview, because 9.3.0 has no idea what that syntax means.

What changed?

  • assets/www/diagram/mermaid.min.js: replaced the bundled 9.3.0 build with 11.12.0, copied verbatim from the CLI source (quarto-cli/src/resources/formats/html/mermaid/mermaid.min.js) so the two stay in lockstep. The CLI build appends globalThis["mermaid"] = ..., which keeps window.mermaid available to the webview's classic <script> load, so no CSP or script-loading changes were needed.
  • assets/www/diagram/diagram.js: migrated to the Mermaid v10+ async API.
    • await mermaid.parse(src) (parse is now async)
    • const { svg } = await mermaid.render(id, src) then inject the returned markup, replacing the removed callback-style render(id, src, cb)
    • dropped the deprecated mermaid.mermaidAPI accessor in favor of mermaid.initialize(...)
    • the webview message handler now awaits the render so render-begin / render-end still bracket the actual render and a queued state update cannot interrupt an in-flight one
    • error reporting falls back through err.str || err.message || String(err) since v11 errors do not always carry .str

Here is what we see afterward:

Screenshot 2026-05-29 at 2 58 11 PM

It's not a perfect match for what you see if you do quarto preview or quarto render; if more folks use this preview we might want to improve it.

FWIW The OJS stdlib pin (packages/ojs/external-observablehq-stdlib/src/dependencies.js, Mermaid 9.2.2) is a separate code path and is intentionally left untouched here because I don't feel very confident about it.

It might be worth thinking about updating this more regularly. 😅

@posit-snyk-bot
Copy link
Copy Markdown
Contributor

posit-snyk-bot commented May 29, 2026

Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
Open Source Security 0 0 0 0 0 issues
Licenses 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

@juliasilge
Copy link
Copy Markdown
Collaborator Author

I added an extension-level test in ebb071a that will warn us the next time we get out of sync on this.

@juliasilge juliasilge requested a review from vezwork May 29, 2026 21:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Upgrade Mermaid to New Version

2 participants