Non-HTML Mermaid rendering fails in sandboxed/restricted environments — request pluggable renderer (e.g. mmdr)

[warnes]

Problem

For HTML output, Quarto renders {mermaid} blocks client-side via bundled mermaid.js — no local process needed. For PDF/DOCX (and other non-HTML formats), Quarto instead rasterizes the diagram at render time by launching a Chromium instance (via Puppeteer or similar), bundled/downloaded by Quarto itself.

This fails outright in any environment that restricts process-level sandboxing of Chromium's multi-process startup — for example, inside Claude Code's built-in sandbox (macOS sandbox-exec/Seatbelt). The failure is identical across Quarto's own downloaded Chromium, a system-installed Google Chrome, and mermaid-cli's bundled Chromium — confirming it's a Chromium-level restriction, not something specific to Quarto's invocation:

bootstrap_check_in org.chromium.Chromium.MachPortRendezvousServer...: Permission denied (1100)

No documented workaround exists

I looked for a config option to swap the renderer or point Quarto at an already-rendered image path automatically, but found none. share/schema/document-mermaid.yml only exposes a theme key, explicitly scoped formats: [$html-files] — confirming there's no supported hook into the non-HTML rasterization path; it appears hardcoded to Puppeteer/Chromium in Quarto's internal JS.

Current workaround

Manually pre-render each .mmd source to a static PNG outside the {mermaid} block and reference it as a regular image, with a Makefile rule to regenerate it. This works but loses the convenience of inline {mermaid} blocks for non-HTML formats.

Suggestion

Consider adding a pluggable/configurable backend for non-HTML Mermaid rasterization — even just an escape hatch to specify an external renderer command — so environments where Chromium can't launch aren't limited to the manual pre-render workaround above. One candidate: mermaid-rs-renderer (mmdr), a pure-Rust Mermaid renderer with no browser dependency at all — takes a .mmd file and outputs SVG/PNG directly. It's not a drop-in replacement (different engine, so layout/text-metrics may not be pixel-identical to Mermaid.js), but as an optional backend it would let Quarto rasterize diagrams for PDF/DOCX in any environment where launching Chromium isn't possible, without requiring an external pre-render step.

Environment

• Quarto (macOS, xelatex/scrreprt PDF output)
• Failure reproduced identically with Quarto's bundled Chromium, system Google Chrome, and mermaid-cli

[mcanouil]

Thanks, but be aware that most repositories have guidelines that you must abide by, regardless of the use of LLM or not.

• https://github.com/quarto-dev/quarto-cli?tab=contributing-ov-file

[mcanouil]

Is there already a "plugable" solution which is a Quarto extension.

• https://github.com/pandoc-ext/diagram

[warnes]

Thanks for the pointer! I just tested it out.

Summary: pandoc-ext/diagram can be made to work with a Chromium-free Mermaid backend (e.g. mmdr) using a small wrapper script, but this showed a different issue specific to Quarto.

execpath in pandoc-ext/diagram's mermaid engine can point at any executable. mmdr's --input/--output flags happen to match mmdc's, so a ~15-line wrapper (drop the unsupported --pdfFit, and shell out to rsvg-convert for the PDF case since mmdr only emits SVG/PNG) is enough to render PDF and DOCX with no browser involved at all.

The catch: Quarto's {mermaid} executable-block syntax is intercepted before any pandoc filter runs, so it never reaches the extension regardless of config, forcing diagrams to be written as plain fenced mermaid code blocks (regular triple-backtick fences, not Quarto's curly-brace syntax). Further, once filters: [diagram] is active, it intercepts those fences for HTML output too, replacing the native client-side mermaid.js render with a static image. Keeping native HTML handling while using the extension for PDF/DOCX requires duplicating the diagram source across two .content-visible when-format=... blocks.

The actual gap: share/schema/document-mermaid.yml's non-HTML path has no execpath-style hook, so providing HTML-native and pluggable-backend handling requires duplicating it across format-specific blocks.