Investigate mermaid-format: svg failures on Linux CI

[cderv]

Description

PR #13702 adds improvements for mermaid-format: svg but tests fail on Linux CI due to timeouts when using Puppeteer to generate SVG files. Tests pass successfully on Windows.

Tests Currently Skipped on Linux

The following tests use skip-on-os: linux until this is resolved:

• tests/docs/smoke-all/2025/11/10/13661.qmd - LaTeX format with mermaid-format:svg - Timed out after 10 minutes
• tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd - DOCX format with mermaid-format:svg - Timed out after 10 minutes
• tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd - GFM format with mermaid-format:svg - Timed out after 10 minutes

Note: tests/docs/smoke-all/2025/11/18/mermaid-gfm-default.qmd does NOT fail because it uses native GFM mermaid code blocks (no Puppeteer required).

Root Cause

When mermaid-format: svg is used, Quarto uses Puppeteer to launch headless Chrome to generate SVG files from mermaid diagrams. On Linux CI, Puppeteer appears to hang indefinitely rather than successfully generating the SVG files or failing cleanly.

Possible causes:

• Missing system dependencies for headless Chrome on Linux
• Chrome/Chromium not properly installed in CI environment
• Puppeteer configuration incompatible with Linux CI environment
• Missing font dependencies causing Chrome to hang

Evidence from CI Logs

From CI run #19461353126:

mermaid-svg-docx.qmd:

[smoke] > quarto render docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd --to docx
'[smoke] > quarto render ...' has been running for over (10m0s)
FAILED (10m0s)

Missing INFO /multi-line text labels may experience clipping/

mermaid-gfm-svg.qmd:

[smoke] > quarto render docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd --to gfm
'[smoke] > quarto render ...' has been running for over (10m0s)
FAILED (10m0s)

No such file or directory (os error 2): readfile 'docs/smoke-all/2025/11/18/mermaid-gfm-svg.md'

The render command hangs and times out after 10 minutes, never completing.

Next Steps

1. Investigate Puppeteer/Chrome dependencies needed for Linux CI
2. Check if Chrome/Chromium is installed in CI runners
3. Review Puppeteer logs for specific error messages (if available)
4. Add required dependencies to CI environment configuration
5. Test that mermaid SVG generation works on Linux
6. Remove skip-on-os: linux from test files once working
7. Verify tests pass on all platforms

Related

• PR Several mermaid-format: svg edge-cases improvement  #13702 - Contains the skip-on-os implementation and skipped tests
• Issue Mermaid-format:svg errors with Beamer target #13661 - Original mermaid-format: svg improvements

Implementation Note

The skip-on-os metadata field was added in PR #13702 to enable OS-specific test filtering in smoke-all tests:

_quarto:
  skip-on-os: linux  # or ["linux", "darwin"] for multiple OSes