From 69a9f0b88d31412c258015e064f0600c317f888c Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 12 Nov 2025 18:17:31 +0100
Subject: [PATCH 01/17] Add smoke test for mermaid-format:svg with Beamer/PDF
 (#13661)

Test expects SVG files to be used directly via \includesvg
without HTML script tags in LaTeX output.

This test should fail initially because setupMermaidSvgJsRuntime()
adds script tags that break LaTeX compilation.
---
 tests/docs/smoke-all/2025/11/10/13661.qmd | 35 +++++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 tests/docs/smoke-all/2025/11/10/13661.qmd

diff --git a/tests/docs/smoke-all/2025/11/10/13661.qmd b/tests/docs/smoke-all/2025/11/10/13661.qmd
new file mode 100644
index 0000000000..2128ebb1d6
--- /dev/null
+++ b/tests/docs/smoke-all/2025/11/10/13661.qmd
@@ -0,0 +1,35 @@
+---
+title: "Mermaid SVG format with Beamer (#13661)"
+format:
+  beamer:
+    mermaid-format: svg
+    keep-tex: true
+  pdf:
+    mermaid-format: svg
+    keep-tex: true
+_quarto:
+  tests:
+    beamer:
+      ensureLatexFileRegexMatches:
+        - ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
+        - ["<script[^>]*>", "mermaid-postprocess-shim"]
+    pdf:
+      ensureLatexFileRegexMatches:
+        - ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
+        - ["<script[^>]*>", "mermaid-postprocess-shim"]
+---
+
+## Test Diagram
+
+Simple mermaid diagram to test SVG format with PDF/Beamer outputs:
+
+```{mermaid}
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Good]
+    B -->|No| D[Bad]
+    C --> E[End]
+    D --> E
+```
+
+This should generate an SVG file and use LaTeX's `\includesvg` command without any HTML script tags.

From c84239e878f7486ed008da6ae661c8eeb5bc09b7 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 12 Nov 2025 18:48:06 +0100
Subject: [PATCH 02/17] lua - path var does not exist

It is `image.src`
---
 src/resources/filters/quarto-post/pdf-images.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/resources/filters/quarto-post/pdf-images.lua b/src/resources/filters/quarto-post/pdf-images.lua
index fc21e3e002..a7a1c86700 100644
--- a/src/resources/filters/quarto-post/pdf-images.lua
+++ b/src/resources/filters/quarto-post/pdf-images.lua
@@ -36,7 +36,7 @@ local function convert_svg(image)
     local stem = pandoc.path.split_extension(image.src)
     local output = stem .. '.pdf'
     if not _quarto.file.exists(output) then
-      warn("Skipping SVG conversion for " .. path .. " because use-rsvg-convert is false, but required PDF file does not exist: " .. output)
+      warn("Skipping SVG conversion for " .. image.src .. " because use-rsvg-convert is false, but required PDF file does not exist: " .. output)
     else
       image.src = output
       return image

From beb64f8a0ec6ac74906283e74cb168f5b4cbfdfc Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 12 Nov 2025 18:49:36 +0100
Subject: [PATCH 03/17] lua - and return nil for true skipping

---
 src/resources/filters/quarto-post/pdf-images.lua | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/resources/filters/quarto-post/pdf-images.lua b/src/resources/filters/quarto-post/pdf-images.lua
index a7a1c86700..daf8a3e5fa 100644
--- a/src/resources/filters/quarto-post/pdf-images.lua
+++ b/src/resources/filters/quarto-post/pdf-images.lua
@@ -37,6 +37,7 @@ local function convert_svg(image)
     local output = stem .. '.pdf'
     if not _quarto.file.exists(output) then
       warn("Skipping SVG conversion for " .. image.src .. " because use-rsvg-convert is false, but required PDF file does not exist: " .. output)
+      return nil
     else
       image.src = output
       return image

From 6a8e07db5457b37afbebb8a860ee64b66d813cbc Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Wed, 12 Nov 2025 20:23:18 +0100
Subject: [PATCH 04/17] Don't include script tag in non-html outputs when svg
 format is selected.

---
 src/core/handlers/mermaid.ts | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/src/core/handlers/mermaid.ts b/src/core/handlers/mermaid.ts
index edb5484bc0..b188e89a02 100644
--- a/src/core/handlers/mermaid.ts
+++ b/src/core/handlers/mermaid.ts
@@ -39,7 +39,7 @@ import { convertFromYaml } from "../lib/yaml-schema/from-yaml.ts";
 import { readYamlFromString } from "../yaml.ts";
 import { pandocHtmlBlock, pandocRawStr } from "../pandoc/codegen.ts";
 import { LocalizedError } from "../lib/located-error.ts";
-import { warning } from "../../deno_ral/log.ts";
+import { info, warning } from "../../deno_ral/log.ts";
 import { FormatDependency } from "../../config/types.ts";
 import { mappedDiff } from "../mapped-text.ts";
 import { escape } from "../../core/lodash.ts";
@@ -228,7 +228,7 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
       ?.[kFigResponsive];
 
     const makeSvg = async () => {
-      setupMermaidSvgJsRuntime();
+      // Extract and process SVG
       let svg = asMappedString(
         (await handlerContext.extractHtml({
           html: content,
@@ -306,7 +306,22 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
         svg = mappedDiff(svg, oldSvgSrc);
       }
 
-      if (isMarkdownOutput(handlerContext.options.format, ["gfm"])) {
+      // For formats that don't support JavaScript runtime (LaTeX/PDF, DOCX, Typst, etc.),
+      // write SVG file directly without postprocess script. This avoids LaTeX compilation
+      // errors from HTML script tags but may result in text clipping in diagrams with
+      // multi-line labels (see https://github.com/quarto-dev/quarto-cli/issues/1622).
+      if (
+        isMarkdownOutput(handlerContext.options.format, ["gfm"]) ||
+        !isJavascriptCompatible(handlerContext.options.format)
+      ) {
+        // Emit info message for non-JS formats (excluding GFM which doesn't have the issue)
+        if (!isMarkdownOutput(handlerContext.options.format, ["gfm"])) {
+          info(
+            `Using mermaid-format: svg with ${
+              handlerContext.options.format.pandoc.to ?? "non-HTML"
+            } format. Note: diagrams with multi-line text labels may experience clipping. Consider using mermaid-format: png if issues occur.`,
+          );
+        }
         const { sourceName, fullName } = handlerContext
           .uniqueFigureName(
             "mermaid-figure-",
@@ -323,6 +338,8 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
           makeFigLink(sourceName, widthInInches, heightInInches, true),
         );
       } else {
+        // For JavaScript-compatible formats, use runtime postprocessing
+        setupMermaidSvgJsRuntime();
         return this.build(
           handlerContext,
           cell,

From 64a810c1f96bcc7df29cce43443e00be8af27b79 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Fri, 14 Nov 2025 20:41:43 +0100
Subject: [PATCH 05/17] Make mermaid-format:svg warning PDF/LaTeX-specific

The warning was shown for all non-JavaScript formats (PDF, LaTeX, Beamer, DOCX, Typst), but only PDF/LaTeX/Beamer require external tooling (rsvg-convert or Inkscape). DOCX and Typst handle SVG natively.

Changed mermaid.ts to use isLatexOutput() instead of !isJavascriptCompatible().
---
 src/core/handlers/mermaid.ts                  |   8 +-
 tests/docs/manual/mermaid-svg-pdf-tooling.qmd | 129 ++++++++++++++++++
 tests/docs/smoke-all/2025/11/10/13661.qmd     |  35 +++--
 .../smoke-all/2025/11/14/mermaid-svg-docx.qmd |  30 ++++
 4 files changed, 183 insertions(+), 19 deletions(-)
 create mode 100644 tests/docs/manual/mermaid-svg-pdf-tooling.qmd
 create mode 100644 tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd

diff --git a/src/core/handlers/mermaid.ts b/src/core/handlers/mermaid.ts
index b188e89a02..1deb2027e6 100644
--- a/src/core/handlers/mermaid.ts
+++ b/src/core/handlers/mermaid.ts
@@ -314,12 +314,12 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
         isMarkdownOutput(handlerContext.options.format, ["gfm"]) ||
         !isJavascriptCompatible(handlerContext.options.format)
       ) {
-        // Emit info message for non-JS formats (excluding GFM which doesn't have the issue)
-        if (!isMarkdownOutput(handlerContext.options.format, ["gfm"])) {
+        // Emit info message for PDF/LaTeX formats (which require external tooling)
+        if (isLatexOutput(handlerContext.options.format.pandoc)) {
           info(
             `Using mermaid-format: svg with ${
-              handlerContext.options.format.pandoc.to ?? "non-HTML"
-            } format. Note: diagrams with multi-line text labels may experience clipping. Consider using mermaid-format: png if issues occur.`,
+              handlerContext.options.format.pandoc.to ?? "PDF"
+            } format requires external tooling (rsvg-convert or Inkscape). Consider using mermaid-format: png if you encounter issues.`,
           );
         }
         const { sourceName, fullName } = handlerContext
diff --git a/tests/docs/manual/mermaid-svg-pdf-tooling.qmd b/tests/docs/manual/mermaid-svg-pdf-tooling.qmd
new file mode 100644
index 0000000000..593b364ac3
--- /dev/null
+++ b/tests/docs/manual/mermaid-svg-pdf-tooling.qmd
@@ -0,0 +1,129 @@
+---
+title: "Manual Test: Mermaid SVG with PDF - External Tooling"
+format:
+  pdf:
+    mermaid-format: svg
+    keep-tex: true
+---
+
+## Purpose
+
+This document is for **manual testing** of mermaid-format:svg with PDF output,
+specifically to verify behavior with different external tooling configurations.
+
+**Why manual?** Automated CI tests cannot easily verify:
+- Actual PDF generation with rsvg-convert
+- Inkscape fallback behavior
+- Platform-specific tooling issues (especially Windows)
+- Full conversion pipeline end-to-end
+
+## Simple Diagram
+
+```{mermaid}
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Good]
+    B -->|No| D[Bad]
+    C --> E[End]
+    D --> E
+```
+
+## Multi-line Labels (Clipping Test)
+
+This tests potential text clipping issues with multi-line labels:
+
+```{mermaid}
+graph TD
+    A["Line 1<br/>Line 2<br/>Line 3"] --> B["Another<br/>Multi<br/>Line<br/>Label"]
+    B --> C["Final<br/>Node"]
+```
+
+## Manual Testing Checklist
+
+### Test 1: With rsvg-convert (Default)
+- [ ] Ensure `rsvg-convert` is on PATH
+- [ ] Run: `quarto render mermaid-svg-pdf-tooling.qmd`
+- [ ] Verify: INFO message includes "requires external tooling"
+- [ ] Verify: PDF generates successfully
+- [ ] Check `.tex` file for `\includesvg` commands
+- [ ] Verify: No script tags in LaTeX output
+- [ ] Open PDF: Diagrams render correctly
+
+### Test 2: Without rsvg-convert
+- [ ] Remove rsvg-convert from PATH or rename binary temporarily
+- [ ] Run: `quarto render mermaid-svg-pdf-tooling.qmd`
+- [ ] Verify: INFO message about tooling requirement
+- [ ] Verify: Error about missing rsvg-convert
+- [ ] Expected behavior: Render fails with clear error
+
+### Test 3: Inkscape Fallback (use-rsvg-convert: false)
+Create variant document with:
+```yaml
+format:
+  pdf:
+    mermaid-format: svg
+    use-rsvg-convert: false
+    pdf-engine-opt: ["-shell-escape"]
+    keep-tex: true
+```
+
+- [ ] Ensure Inkscape is installed
+- [ ] Run render with above config
+- [ ] Verify: INFO message about tooling
+- [ ] Verify: PDF generates via Inkscape (check logs)
+- [ ] Check `.tex` file: uses `\includesvg` with Inkscape
+- [ ] Open PDF: Diagrams render correctly
+
+### Test 4: Windows-Specific
+- [ ] Test on Windows with rsvg-convert (if available via Scoop/other)
+- [ ] Test on Windows without rsvg-convert
+- [ ] Test Inkscape fallback on Windows
+- [ ] Document any Windows-specific issues
+
+### Test 5: Comparison with PNG (Control)
+Create variant with `mermaid-format: png`:
+
+- [ ] Run: `quarto render` with png format
+- [ ] Verify: NO warning about external tooling
+- [ ] Verify: PDF generates successfully
+- [ ] Quality comparison: SVG vs PNG in final PDF
+
+## Expected Results Summary
+
+| Scenario | Warning | PDF Generation | Notes |
+|----------|---------|----------------|-------|
+| rsvg-convert available | ✅ Yes | ✅ Success | Default path |
+| No rsvg-convert | ✅ Yes | ❌ Error | Clear error message |
+| Inkscape + shell-escape | ✅ Yes | ✅ Success | Fallback works |
+| PNG format | ❌ No | ✅ Success | No tooling needed |
+
+## Platform-Specific Notes
+
+### Linux/Mac
+- rsvg-convert typically available via package managers
+- `librsvg` package usually includes rsvg-convert
+- Inkscape widely available
+
+### Windows
+- rsvg-convert NOT easily available (complex setup)
+- Can use Scoop: `scoop install rsvg-convert` (if r-bucket configured)
+- Inkscape available but requires shell-escape configuration
+- Most users should prefer PNG format on Windows
+
+## Recording Results
+
+After completing manual tests, document results in the beads issue notes field
+for quarto-cli-idi. Include:
+
+- Platforms tested (OS, versions)
+- Which scenarios passed/failed
+- Any unexpected behavior
+- Screenshots if helpful
+- Recommendations for users
+
+## See Also
+
+- Automated test: `tests/docs/smoke-all/2025/11/10/13661.qmd`
+- DOCX test: `tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd`
+- Beads issue: quarto-cli-idi
+- GitHub issue: #13661
diff --git a/tests/docs/smoke-all/2025/11/10/13661.qmd b/tests/docs/smoke-all/2025/11/10/13661.qmd
index 2128ebb1d6..c49f96e44e 100644
--- a/tests/docs/smoke-all/2025/11/10/13661.qmd
+++ b/tests/docs/smoke-all/2025/11/10/13661.qmd
@@ -1,27 +1,34 @@
 ---
-title: "Mermaid SVG format with Beamer (#13661)"
+title: "Mermaid SVG format with LaTeX - No script tags (#13661)"
+# Test strategy: Use format:latex with use-rsvg-convert:false to:
+# - Test mermaid-format:svg (the actual bug scenario)
+# - Generate .tex file without compiling PDF (avoids needing rsvg-convert/Inkscape in CI)
+# - Verify warning message about external tooling
+# - Verify LaTeX uses \includesvg (not \includegraphics)
+# - Verify NO HTML <script> tags in LaTeX output (the original bug)
 format:
-  beamer:
+  latex:
     mermaid-format: svg
-    keep-tex: true
-  pdf:
-    mermaid-format: svg
-    keep-tex: true
+    use-rsvg-convert: false
 _quarto:
   tests:
-    beamer:
-      ensureLatexFileRegexMatches:
-        - ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
-        - ["<script[^>]*>", "mermaid-postprocess-shim"]
-    pdf:
-      ensureLatexFileRegexMatches:
+    latex:
+      printsMessage:
+        level: INFO
+        regex: 'requires external tooling'
+      ensureFileRegexMatches:
         - ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
         - ["<script[^>]*>", "mermaid-postprocess-shim"]
 ---
 
 ## Test Diagram
 
-Simple mermaid diagram to test SVG format with PDF/Beamer outputs:
+Simple mermaid diagram to test SVG format with LaTeX output.
+
+**What this tests:**
+- Bug fix: HTML script tags should NOT appear in LaTeX output
+- Warning: Should emit INFO about requiring external tooling (rsvg-convert or Inkscape)
+- LaTeX structure: Should use `\includesvg` command for SVG files
 
 ```{mermaid}
 graph TD
@@ -31,5 +38,3 @@ graph TD
     C --> E[End]
     D --> E
 ```
-
-This should generate an SVG file and use LaTeX's `\includesvg` command without any HTML script tags.
diff --git a/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd b/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
new file mode 100644
index 0000000000..00de417026
--- /dev/null
+++ b/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
@@ -0,0 +1,30 @@
+---
+title: "Mermaid SVG with DOCX - No tooling warning expected (#13661)"
+format:
+  docx:
+    mermaid-format: svg
+_quarto:
+  tests:
+    docx:
+      printsMessage:
+        level: INFO
+        regex: 'requires external tooling'
+        negate: true
+---
+
+## Test Diagram
+
+This tests that DOCX format with mermaid-format:svg does NOT emit
+the "requires external tooling" warning (since DOCX handles SVG natively).
+
+```{mermaid}
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Good]
+    B -->|No| D[Bad]
+    C --> E[End]
+    D --> E
+```
+
+Expected: No warning about external tooling (rsvg-convert/Inkscape).
+DOCX format handles SVG natively without requiring external converters.

From 9366daf13bb0eda0c1245807b77686066c0d6ca9 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Fri, 14 Nov 2025 20:55:46 +0100
Subject: [PATCH 06/17] Revert "Make mermaid-format:svg warning
 PDF/LaTeX-specific"

This reverts commit 64a810c1f96bcc7df29cce43443e00be8af27b79.
---
 src/core/handlers/mermaid.ts                  |   8 +-
 tests/docs/manual/mermaid-svg-pdf-tooling.qmd | 129 ------------------
 tests/docs/smoke-all/2025/11/10/13661.qmd     |  35 ++---
 .../smoke-all/2025/11/14/mermaid-svg-docx.qmd |  30 ----
 4 files changed, 19 insertions(+), 183 deletions(-)
 delete mode 100644 tests/docs/manual/mermaid-svg-pdf-tooling.qmd
 delete mode 100644 tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd

diff --git a/src/core/handlers/mermaid.ts b/src/core/handlers/mermaid.ts
index 1deb2027e6..b188e89a02 100644
--- a/src/core/handlers/mermaid.ts
+++ b/src/core/handlers/mermaid.ts
@@ -314,12 +314,12 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
         isMarkdownOutput(handlerContext.options.format, ["gfm"]) ||
         !isJavascriptCompatible(handlerContext.options.format)
       ) {
-        // Emit info message for PDF/LaTeX formats (which require external tooling)
-        if (isLatexOutput(handlerContext.options.format.pandoc)) {
+        // Emit info message for non-JS formats (excluding GFM which doesn't have the issue)
+        if (!isMarkdownOutput(handlerContext.options.format, ["gfm"])) {
           info(
             `Using mermaid-format: svg with ${
-              handlerContext.options.format.pandoc.to ?? "PDF"
-            } format requires external tooling (rsvg-convert or Inkscape). Consider using mermaid-format: png if you encounter issues.`,
+              handlerContext.options.format.pandoc.to ?? "non-HTML"
+            } format. Note: diagrams with multi-line text labels may experience clipping. Consider using mermaid-format: png if issues occur.`,
           );
         }
         const { sourceName, fullName } = handlerContext
diff --git a/tests/docs/manual/mermaid-svg-pdf-tooling.qmd b/tests/docs/manual/mermaid-svg-pdf-tooling.qmd
deleted file mode 100644
index 593b364ac3..0000000000
--- a/tests/docs/manual/mermaid-svg-pdf-tooling.qmd
+++ /dev/null
@@ -1,129 +0,0 @@
----
-title: "Manual Test: Mermaid SVG with PDF - External Tooling"
-format:
-  pdf:
-    mermaid-format: svg
-    keep-tex: true
----
-
-## Purpose
-
-This document is for **manual testing** of mermaid-format:svg with PDF output,
-specifically to verify behavior with different external tooling configurations.
-
-**Why manual?** Automated CI tests cannot easily verify:
-- Actual PDF generation with rsvg-convert
-- Inkscape fallback behavior
-- Platform-specific tooling issues (especially Windows)
-- Full conversion pipeline end-to-end
-
-## Simple Diagram
-
-```{mermaid}
-graph TD
-    A[Start] --> B{Decision}
-    B -->|Yes| C[Good]
-    B -->|No| D[Bad]
-    C --> E[End]
-    D --> E
-```
-
-## Multi-line Labels (Clipping Test)
-
-This tests potential text clipping issues with multi-line labels:
-
-```{mermaid}
-graph TD
-    A["Line 1<br/>Line 2<br/>Line 3"] --> B["Another<br/>Multi<br/>Line<br/>Label"]
-    B --> C["Final<br/>Node"]
-```
-
-## Manual Testing Checklist
-
-### Test 1: With rsvg-convert (Default)
-- [ ] Ensure `rsvg-convert` is on PATH
-- [ ] Run: `quarto render mermaid-svg-pdf-tooling.qmd`
-- [ ] Verify: INFO message includes "requires external tooling"
-- [ ] Verify: PDF generates successfully
-- [ ] Check `.tex` file for `\includesvg` commands
-- [ ] Verify: No script tags in LaTeX output
-- [ ] Open PDF: Diagrams render correctly
-
-### Test 2: Without rsvg-convert
-- [ ] Remove rsvg-convert from PATH or rename binary temporarily
-- [ ] Run: `quarto render mermaid-svg-pdf-tooling.qmd`
-- [ ] Verify: INFO message about tooling requirement
-- [ ] Verify: Error about missing rsvg-convert
-- [ ] Expected behavior: Render fails with clear error
-
-### Test 3: Inkscape Fallback (use-rsvg-convert: false)
-Create variant document with:
-```yaml
-format:
-  pdf:
-    mermaid-format: svg
-    use-rsvg-convert: false
-    pdf-engine-opt: ["-shell-escape"]
-    keep-tex: true
-```
-
-- [ ] Ensure Inkscape is installed
-- [ ] Run render with above config
-- [ ] Verify: INFO message about tooling
-- [ ] Verify: PDF generates via Inkscape (check logs)
-- [ ] Check `.tex` file: uses `\includesvg` with Inkscape
-- [ ] Open PDF: Diagrams render correctly
-
-### Test 4: Windows-Specific
-- [ ] Test on Windows with rsvg-convert (if available via Scoop/other)
-- [ ] Test on Windows without rsvg-convert
-- [ ] Test Inkscape fallback on Windows
-- [ ] Document any Windows-specific issues
-
-### Test 5: Comparison with PNG (Control)
-Create variant with `mermaid-format: png`:
-
-- [ ] Run: `quarto render` with png format
-- [ ] Verify: NO warning about external tooling
-- [ ] Verify: PDF generates successfully
-- [ ] Quality comparison: SVG vs PNG in final PDF
-
-## Expected Results Summary
-
-| Scenario | Warning | PDF Generation | Notes |
-|----------|---------|----------------|-------|
-| rsvg-convert available | ✅ Yes | ✅ Success | Default path |
-| No rsvg-convert | ✅ Yes | ❌ Error | Clear error message |
-| Inkscape + shell-escape | ✅ Yes | ✅ Success | Fallback works |
-| PNG format | ❌ No | ✅ Success | No tooling needed |
-
-## Platform-Specific Notes
-
-### Linux/Mac
-- rsvg-convert typically available via package managers
-- `librsvg` package usually includes rsvg-convert
-- Inkscape widely available
-
-### Windows
-- rsvg-convert NOT easily available (complex setup)
-- Can use Scoop: `scoop install rsvg-convert` (if r-bucket configured)
-- Inkscape available but requires shell-escape configuration
-- Most users should prefer PNG format on Windows
-
-## Recording Results
-
-After completing manual tests, document results in the beads issue notes field
-for quarto-cli-idi. Include:
-
-- Platforms tested (OS, versions)
-- Which scenarios passed/failed
-- Any unexpected behavior
-- Screenshots if helpful
-- Recommendations for users
-
-## See Also
-
-- Automated test: `tests/docs/smoke-all/2025/11/10/13661.qmd`
-- DOCX test: `tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd`
-- Beads issue: quarto-cli-idi
-- GitHub issue: #13661
diff --git a/tests/docs/smoke-all/2025/11/10/13661.qmd b/tests/docs/smoke-all/2025/11/10/13661.qmd
index c49f96e44e..2128ebb1d6 100644
--- a/tests/docs/smoke-all/2025/11/10/13661.qmd
+++ b/tests/docs/smoke-all/2025/11/10/13661.qmd
@@ -1,34 +1,27 @@
 ---
-title: "Mermaid SVG format with LaTeX - No script tags (#13661)"
-# Test strategy: Use format:latex with use-rsvg-convert:false to:
-# - Test mermaid-format:svg (the actual bug scenario)
-# - Generate .tex file without compiling PDF (avoids needing rsvg-convert/Inkscape in CI)
-# - Verify warning message about external tooling
-# - Verify LaTeX uses \includesvg (not \includegraphics)
-# - Verify NO HTML <script> tags in LaTeX output (the original bug)
+title: "Mermaid SVG format with Beamer (#13661)"
 format:
-  latex:
+  beamer:
     mermaid-format: svg
-    use-rsvg-convert: false
+    keep-tex: true
+  pdf:
+    mermaid-format: svg
+    keep-tex: true
 _quarto:
   tests:
-    latex:
-      printsMessage:
-        level: INFO
-        regex: 'requires external tooling'
-      ensureFileRegexMatches:
+    beamer:
+      ensureLatexFileRegexMatches:
+        - ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
+        - ["<script[^>]*>", "mermaid-postprocess-shim"]
+    pdf:
+      ensureLatexFileRegexMatches:
         - ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
         - ["<script[^>]*>", "mermaid-postprocess-shim"]
 ---
 
 ## Test Diagram
 
-Simple mermaid diagram to test SVG format with LaTeX output.
-
-**What this tests:**
-- Bug fix: HTML script tags should NOT appear in LaTeX output
-- Warning: Should emit INFO about requiring external tooling (rsvg-convert or Inkscape)
-- LaTeX structure: Should use `\includesvg` command for SVG files
+Simple mermaid diagram to test SVG format with PDF/Beamer outputs:
 
 ```{mermaid}
 graph TD
@@ -38,3 +31,5 @@ graph TD
     C --> E[End]
     D --> E
 ```
+
+This should generate an SVG file and use LaTeX's `\includesvg` command without any HTML script tags.
diff --git a/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd b/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
deleted file mode 100644
index 00de417026..0000000000
--- a/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
+++ /dev/null
@@ -1,30 +0,0 @@
----
-title: "Mermaid SVG with DOCX - No tooling warning expected (#13661)"
-format:
-  docx:
-    mermaid-format: svg
-_quarto:
-  tests:
-    docx:
-      printsMessage:
-        level: INFO
-        regex: 'requires external tooling'
-        negate: true
----
-
-## Test Diagram
-
-This tests that DOCX format with mermaid-format:svg does NOT emit
-the "requires external tooling" warning (since DOCX handles SVG natively).
-
-```{mermaid}
-graph TD
-    A[Start] --> B{Decision}
-    B -->|Yes| C[Good]
-    B -->|No| D[Bad]
-    C --> E[End]
-    D --> E
-```
-
-Expected: No warning about external tooling (rsvg-convert/Inkscape).
-DOCX format handles SVG natively without requiring external converters.

From a537370a667d10a6bb426fc7ee2a867607ddb324 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Fri, 14 Nov 2025 21:06:22 +0100
Subject: [PATCH 07/17] Warn about SVG clipping for all non-JS formats, plus
 tooling for LaTeX

SVG format without JavaScript postprocessing may have text clipping issues with multi-line labels. LaTeX-based formats additionally require external tooling (rsvg-convert or Inkscape).

Updated mermaid.ts to emit comprehensive warnings for non-JavaScript formats.

Test coverage:
- LaTeX test verifies both clipping + tooling warnings
- DOCX test verifies clipping warning only
- Manual testing checklist for full validation
---
 src/core/handlers/mermaid.ts                  |  17 ++-
 tests/docs/manual/mermaid-svg-pdf-tooling.qmd | 129 ++++++++++++++++++
 tests/docs/smoke-all/2025/11/10/13661.qmd     |  35 +++--
 .../smoke-all/2025/11/14/mermaid-svg-docx.qmd |  29 ++++
 4 files changed, 190 insertions(+), 20 deletions(-)
 create mode 100644 tests/docs/manual/mermaid-svg-pdf-tooling.qmd
 create mode 100644 tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd

diff --git a/src/core/handlers/mermaid.ts b/src/core/handlers/mermaid.ts
index b188e89a02..8bef0cd184 100644
--- a/src/core/handlers/mermaid.ts
+++ b/src/core/handlers/mermaid.ts
@@ -316,11 +316,18 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
       ) {
         // Emit info message for non-JS formats (excluding GFM which doesn't have the issue)
         if (!isMarkdownOutput(handlerContext.options.format, ["gfm"])) {
-          info(
-            `Using mermaid-format: svg with ${
-              handlerContext.options.format.pandoc.to ?? "non-HTML"
-            } format. Note: diagrams with multi-line text labels may experience clipping. Consider using mermaid-format: png if issues occur.`,
-          );
+          let warning = `Using mermaid-format: svg with ${
+            handlerContext.options.format.pandoc.to ?? "non-HTML"
+          } format. Note: diagrams with multi-line text labels may experience clipping`;
+
+          // LaTeX-based formats also require external tooling
+          if (isLatexOutput(handlerContext.options.format.pandoc)) {
+            warning += " and requires external tooling (rsvg-convert or Inkscape)";
+          }
+
+          warning += ". Consider using mermaid-format: png if issues occur.";
+
+          info(warning);
         }
         const { sourceName, fullName } = handlerContext
           .uniqueFigureName(
diff --git a/tests/docs/manual/mermaid-svg-pdf-tooling.qmd b/tests/docs/manual/mermaid-svg-pdf-tooling.qmd
new file mode 100644
index 0000000000..593b364ac3
--- /dev/null
+++ b/tests/docs/manual/mermaid-svg-pdf-tooling.qmd
@@ -0,0 +1,129 @@
+---
+title: "Manual Test: Mermaid SVG with PDF - External Tooling"
+format:
+  pdf:
+    mermaid-format: svg
+    keep-tex: true
+---
+
+## Purpose
+
+This document is for **manual testing** of mermaid-format:svg with PDF output,
+specifically to verify behavior with different external tooling configurations.
+
+**Why manual?** Automated CI tests cannot easily verify:
+- Actual PDF generation with rsvg-convert
+- Inkscape fallback behavior
+- Platform-specific tooling issues (especially Windows)
+- Full conversion pipeline end-to-end
+
+## Simple Diagram
+
+```{mermaid}
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Good]
+    B -->|No| D[Bad]
+    C --> E[End]
+    D --> E
+```
+
+## Multi-line Labels (Clipping Test)
+
+This tests potential text clipping issues with multi-line labels:
+
+```{mermaid}
+graph TD
+    A["Line 1<br/>Line 2<br/>Line 3"] --> B["Another<br/>Multi<br/>Line<br/>Label"]
+    B --> C["Final<br/>Node"]
+```
+
+## Manual Testing Checklist
+
+### Test 1: With rsvg-convert (Default)
+- [ ] Ensure `rsvg-convert` is on PATH
+- [ ] Run: `quarto render mermaid-svg-pdf-tooling.qmd`
+- [ ] Verify: INFO message includes "requires external tooling"
+- [ ] Verify: PDF generates successfully
+- [ ] Check `.tex` file for `\includesvg` commands
+- [ ] Verify: No script tags in LaTeX output
+- [ ] Open PDF: Diagrams render correctly
+
+### Test 2: Without rsvg-convert
+- [ ] Remove rsvg-convert from PATH or rename binary temporarily
+- [ ] Run: `quarto render mermaid-svg-pdf-tooling.qmd`
+- [ ] Verify: INFO message about tooling requirement
+- [ ] Verify: Error about missing rsvg-convert
+- [ ] Expected behavior: Render fails with clear error
+
+### Test 3: Inkscape Fallback (use-rsvg-convert: false)
+Create variant document with:
+```yaml
+format:
+  pdf:
+    mermaid-format: svg
+    use-rsvg-convert: false
+    pdf-engine-opt: ["-shell-escape"]
+    keep-tex: true
+```
+
+- [ ] Ensure Inkscape is installed
+- [ ] Run render with above config
+- [ ] Verify: INFO message about tooling
+- [ ] Verify: PDF generates via Inkscape (check logs)
+- [ ] Check `.tex` file: uses `\includesvg` with Inkscape
+- [ ] Open PDF: Diagrams render correctly
+
+### Test 4: Windows-Specific
+- [ ] Test on Windows with rsvg-convert (if available via Scoop/other)
+- [ ] Test on Windows without rsvg-convert
+- [ ] Test Inkscape fallback on Windows
+- [ ] Document any Windows-specific issues
+
+### Test 5: Comparison with PNG (Control)
+Create variant with `mermaid-format: png`:
+
+- [ ] Run: `quarto render` with png format
+- [ ] Verify: NO warning about external tooling
+- [ ] Verify: PDF generates successfully
+- [ ] Quality comparison: SVG vs PNG in final PDF
+
+## Expected Results Summary
+
+| Scenario | Warning | PDF Generation | Notes |
+|----------|---------|----------------|-------|
+| rsvg-convert available | ✅ Yes | ✅ Success | Default path |
+| No rsvg-convert | ✅ Yes | ❌ Error | Clear error message |
+| Inkscape + shell-escape | ✅ Yes | ✅ Success | Fallback works |
+| PNG format | ❌ No | ✅ Success | No tooling needed |
+
+## Platform-Specific Notes
+
+### Linux/Mac
+- rsvg-convert typically available via package managers
+- `librsvg` package usually includes rsvg-convert
+- Inkscape widely available
+
+### Windows
+- rsvg-convert NOT easily available (complex setup)
+- Can use Scoop: `scoop install rsvg-convert` (if r-bucket configured)
+- Inkscape available but requires shell-escape configuration
+- Most users should prefer PNG format on Windows
+
+## Recording Results
+
+After completing manual tests, document results in the beads issue notes field
+for quarto-cli-idi. Include:
+
+- Platforms tested (OS, versions)
+- Which scenarios passed/failed
+- Any unexpected behavior
+- Screenshots if helpful
+- Recommendations for users
+
+## See Also
+
+- Automated test: `tests/docs/smoke-all/2025/11/10/13661.qmd`
+- DOCX test: `tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd`
+- Beads issue: quarto-cli-idi
+- GitHub issue: #13661
diff --git a/tests/docs/smoke-all/2025/11/10/13661.qmd b/tests/docs/smoke-all/2025/11/10/13661.qmd
index 2128ebb1d6..01f4a86a32 100644
--- a/tests/docs/smoke-all/2025/11/10/13661.qmd
+++ b/tests/docs/smoke-all/2025/11/10/13661.qmd
@@ -1,27 +1,34 @@
 ---
-title: "Mermaid SVG format with Beamer (#13661)"
+title: "Mermaid SVG format with LaTeX - No script tags (#13661)"
+# Test strategy: Use format:latex with use-rsvg-convert:false to:
+# - Test mermaid-format:svg (the actual bug scenario)
+# - Generate .tex file without compiling PDF (avoids needing rsvg-convert/Inkscape in CI)
+# - Verify warning message about clipping + external tooling
+# - Verify LaTeX uses \includesvg (not \includegraphics)
+# - Verify NO HTML <script> tags in LaTeX output (the original bug)
 format:
-  beamer:
+  latex:
     mermaid-format: svg
-    keep-tex: true
-  pdf:
-    mermaid-format: svg
-    keep-tex: true
+    use-rsvg-convert: false
 _quarto:
   tests:
-    beamer:
-      ensureLatexFileRegexMatches:
-        - ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
-        - ["<script[^>]*>", "mermaid-postprocess-shim"]
-    pdf:
-      ensureLatexFileRegexMatches:
+    latex:
+      printsMessage:
+        level: INFO
+        regex: 'multi-line text labels may experience clipping.*requires external tooling'
+      ensureFileRegexMatches:
         - ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
         - ["<script[^>]*>", "mermaid-postprocess-shim"]
 ---
 
 ## Test Diagram
 
-Simple mermaid diagram to test SVG format with PDF/Beamer outputs:
+Simple mermaid diagram to test SVG format with LaTeX output.
+
+**What this tests:**
+- Bug fix: HTML script tags should NOT appear in LaTeX output
+- Warning: Should emit INFO about clipping AND requiring external tooling
+- LaTeX structure: Should use `\includesvg` command for SVG files
 
 ```{mermaid}
 graph TD
@@ -31,5 +38,3 @@ graph TD
     C --> E[End]
     D --> E
 ```
-
-This should generate an SVG file and use LaTeX's `\includesvg` command without any HTML script tags.
diff --git a/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd b/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
new file mode 100644
index 0000000000..0dee48fc9a
--- /dev/null
+++ b/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
@@ -0,0 +1,29 @@
+---
+title: "Mermaid SVG with DOCX - Clipping warning expected (#13661)"
+format:
+  docx:
+    mermaid-format: svg
+_quarto:
+  tests:
+    docx:
+      printsMessage:
+        level: INFO
+        regex: 'multi-line text labels may experience clipping'
+---
+
+## Test Diagram
+
+This tests that DOCX format with mermaid-format:svg emits a warning about
+potential text clipping issues (but NOT about external tooling requirements).
+
+```{mermaid}
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Good]
+    B -->|No| D[Bad]
+    C --> E[End]
+    D --> E
+```
+
+Expected: Warning about text clipping in multi-line labels.
+NOT expected: Warning about rsvg-convert/Inkscape (DOCX doesn't strictly require it).

From bd4efaa712aa0120a17262a859e5f8ff1f6035e1 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Mon, 17 Nov 2025 15:48:39 +0100
Subject: [PATCH 08/17] Update changelog for the fix

and add mention of limitations
---
 news/changelog-1.9.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/news/changelog-1.9.md b/news/changelog-1.9.md
index be96d684a8..da6de3c010 100644
--- a/news/changelog-1.9.md
+++ b/news/changelog-1.9.md
@@ -41,6 +41,7 @@ All changes included in 1.9:
 ### `pdf`
 
 - ([#10291](https://github.com/quarto-dev/quarto-cli/issues/10291)): Fix detection of babel hyphenation warnings with straight-quote format instead of backtick-quote format.
+- ([#13661](https://github.com/quarto-dev/quarto-cli/issues/13661)): Fix LaTeX compilation errors when using `mermaid-format: svg` with PDF/LaTeX output. SVG diagrams are now written directly without HTML script tags. Note: `mermaid-format: png` is recommended for best compatibility. SVG format requires `rsvg-convert` (or Inkscape with `use-rsvg-convert: false`) in PATH for conversion to PDF, and may experience text clipping in diagrams with multi-line labels.
 - ([rstudio/tinytex-releases#49](https://github.com/rstudio/tinytex-releases/issues/49)): Fix detection of LuaTeX-ja missing file errors by matching both "File" and "file" in error messages.
 
 ## Projects

From 47a497a3b04d0c4a56ad0edb04903f37fd7d6061 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Mon, 17 Nov 2025 17:40:51 +0100
Subject: [PATCH 09/17] test - document difference in test context between
 ignore and prereq

---
 tests/test.ts | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/tests/test.ts b/tests/test.ts
index 6390aea40e..562b415246 100644
--- a/tests/test.ts
+++ b/tests/test.ts
@@ -52,7 +52,13 @@ export interface TestDescriptor {
 export interface TestContext {
   name?: string;
 
-  // Checks that prereqs for the test are met
+  // Checks that prereqs for the test are met (async conditional skip)
+  // - Returns false: Test is SKIPPED with warning message (not failed)
+  // - Throws/rejects: Test is SKIPPED (initialization failed gracefully)
+  // Use cases:
+  //   - Tool availability checks (e.g., which("rsvg-convert"))
+  //   - Initialization that might fail (e.g., schema loading)
+  // Difference from ignore: Can be async, runs inside test, handles exceptions
   prereq?: () => Promise<boolean>;
 
   // Cleans up the test
@@ -67,7 +73,14 @@ export interface TestContext {
   // Control of underlying sanitizer
   sanitize?: { resources?: boolean; ops?: boolean; exit?: boolean };
 
-  // control if test is ran or skipped
+  // Control if test is ran or skipped (static boolean only)
+  // - true: Test is completely IGNORED by Deno (not run, not counted)
+  // - false: Test runs normally
+  // Use cases:
+  //   - Static platform checks (e.g., isWindows)
+  //   - Static configuration flags
+  // Limitation: Must be a simple boolean value computed at registration time
+  // For dynamic/async conditional skip (e.g., tool availability), use prereq instead
   ignore?: boolean;
 
   // environment to pass to downstream processes

From 6dfec1712a50a104472619743c9142a18cb39b98 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Mon, 17 Nov 2025 22:35:26 +0100
Subject: [PATCH 10/17] Move rsvg-convert SVG conversion tests to smoke tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Migrates SVG to PDF conversion tests from smoke-all to smoke tests with conditional execution based on rsvg-convert availability.

Old smoke-all tests couldn't conditionally test based on tool availability or verify proper error messages.

New test structure:
- Test 1: With rsvg-convert - verifies successful SVG→PDF conversion
- Test 2: Without rsvg-convert, with pre-converted PDF - uses existing PDF, verifies warning message
- Test 3: Without rsvg-convert, no PDF - verifies warning and LaTeX \includesvg usage

Uses which('rsvg-convert')  to conditionally run tests based on tool availability.
---
 .../smoke-all/2024/01/26/issue-8299-1.qmd     |  11 ---
 .../smoke-all/2024/01/26/issue-8299-2.qmd     |  12 ---
 tests/docs/svg-conversion/test-no-pdf.svg     |   4 +
 .../with-rsvg-with-pdf/index.qmd              |  11 +++
 .../with-rsvg-with-pdf/simple-svg.pdf         | Bin 0 -> 1077 bytes
 .../with-rsvg-with-pdf/simple-svg.svg         |   3 +
 tests/docs/svg-conversion/with-rsvg/index.qmd |  12 +++
 .../svg-conversion/with-rsvg/simple-svg.svg   |   3 +
 .../svg-conversion/without-rsvg-no-pdf.qmd    |  13 ++++
 .../render/render-pdf-svg-conversion.test.ts  |  73 ++++++++++++++++++
 10 files changed, 119 insertions(+), 23 deletions(-)
 delete mode 100644 tests/docs/smoke-all/2024/01/26/issue-8299-1.qmd
 delete mode 100644 tests/docs/smoke-all/2024/01/26/issue-8299-2.qmd
 create mode 100644 tests/docs/svg-conversion/test-no-pdf.svg
 create mode 100644 tests/docs/svg-conversion/with-rsvg-with-pdf/index.qmd
 create mode 100644 tests/docs/svg-conversion/with-rsvg-with-pdf/simple-svg.pdf
 create mode 100644 tests/docs/svg-conversion/with-rsvg-with-pdf/simple-svg.svg
 create mode 100644 tests/docs/svg-conversion/with-rsvg/index.qmd
 create mode 100644 tests/docs/svg-conversion/with-rsvg/simple-svg.svg
 create mode 100644 tests/docs/svg-conversion/without-rsvg-no-pdf.qmd
 create mode 100644 tests/smoke/render/render-pdf-svg-conversion.test.ts

diff --git a/tests/docs/smoke-all/2024/01/26/issue-8299-1.qmd b/tests/docs/smoke-all/2024/01/26/issue-8299-1.qmd
deleted file mode 100644
index b4227a1458..0000000000
--- a/tests/docs/smoke-all/2024/01/26/issue-8299-1.qmd
+++ /dev/null
@@ -1,11 +0,0 @@
----
-title: issue-8299
-format: pdf
-_quarto:
-  tests:
-    pdf:
-      fileExists: 
-        outputPath: simple-svg.pdf
----
-
-![An image we would otherwise trounce](simple-svg.svg)
\ No newline at end of file
diff --git a/tests/docs/smoke-all/2024/01/26/issue-8299-2.qmd b/tests/docs/smoke-all/2024/01/26/issue-8299-2.qmd
deleted file mode 100644
index d2b57dd2f3..0000000000
--- a/tests/docs/smoke-all/2024/01/26/issue-8299-2.qmd
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: issue-8299-2
-format: latex
-use-rsvg-convert: false
-_quarto:
-  tests:
-    latex:
-      ensureFileRegexMatches:
-        - ["simple-svg.pdf"]
----
-
-![An SVG image that exists as PDF in the filesystem and will be transparently converted](simple-svg.svg)
\ No newline at end of file
diff --git a/tests/docs/svg-conversion/test-no-pdf.svg b/tests/docs/svg-conversion/test-no-pdf.svg
new file mode 100644
index 0000000000..d50c436353
--- /dev/null
+++ b/tests/docs/svg-conversion/test-no-pdf.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+  <rect width="100" height="100" fill="#336699"/>
+  <text x="50" y="55" font-family="Arial" font-size="16" fill="white" text-anchor="middle">NO PDF</text>
+</svg>
diff --git a/tests/docs/svg-conversion/with-rsvg-with-pdf/index.qmd b/tests/docs/svg-conversion/with-rsvg-with-pdf/index.qmd
new file mode 100644
index 0000000000..e227d8c1c4
--- /dev/null
+++ b/tests/docs/svg-conversion/with-rsvg-with-pdf/index.qmd
@@ -0,0 +1,11 @@
+---
+title: "SVG to PDF without rsvg-convert (pre-converted PDF exists)"
+format: pdf
+keep-tex: true
+---
+
+This test verifies that rendering works when rsvg-convert is disabled but a pre-converted PDF exists.
+
+The filter should use the existing simple-svg.pdf file without conversion or warnings.
+
+![Test SVG image with pre-converted PDF](simple-svg.svg)
diff --git a/tests/docs/svg-conversion/with-rsvg-with-pdf/simple-svg.pdf b/tests/docs/svg-conversion/with-rsvg-with-pdf/simple-svg.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..d903d28a451401f220b628331bff864ccb0492f2
GIT binary patch
literal 1077
zcmY!laB<T$)HCN&-THRjZ!QxB1BLvgEG`=x1%02?y!4U`1yi6<5SN02g1%d3PDyGJ
zkj_agNp(q0&QD3@va{nVE-6Y)%;l<>V;o|@;1uhukeIh>!kp8gCsG;2w7kME_?rZH
z=s#oXlAir~rq+|DkQq@gBqgN|Y0MDuSlzU6=DeM)svWrulg%4E)R`p(BK2lyt>|G4
z;9DoQLO78vB$;i}*UXs47>0L-N|s!yc_~oqfGm(hL9PSQK=&CM7=YwKJY%>wzz%n<
zC~*%i0Xka2#s(w+1p0{vK#qdGv!jBcf_`!$kOX=KC;=pa2x^Ww+#Ch{kjjEo1%3ad
ztl*Mdu&L1Sv4Dq<pMoJ+!Y#9?xJ1DO$|ewI!3Gbyo^?HCVqmjijK%aH$aI+h%wW#4
zB*IySMo8|0xdr4dBV(c*7CP}@R*Qi^+k3mCF<xH-d^bg%R;rF@T{`8^qjzh+2t0bg
z)-_RO+PmB3i(XGl()(=q_`mO=M%Oux2bCE2JP>@oLDMxPbi&;A%1&idY<F=mY%;%V
z`GbLxC+f$Xz}#gAnfuFjS3b({HP_rCpuKV}<GfGPr#RMptSh;#GdnZ?X~o4;OOJi?
z-1O(zqA$02dcSZKZWi@<($k$D_Uy@*Bd6StO)`Dr&n>56bw+;a(FcNO(mwRfomTzX
zc~{TAO&sZ=ayF*cC*I#>&t4|DN=sy6oKV`XMZ$sF?B;DMrLiBiE36+zUA=Pk!S=8l
za^Dyy6+Y0lGLCHJGy8r<m{)6mhjmqR{pqWhPU~O3U$*%7{<Utt`vZ;hvM}QY9K_Jb
zF)}xW#f~8&^}$k2L{MrPa+)!<z!?Xiv>BXPm8xI}iL`KqXhQ`f1*2H7j-dSf5(Ps;
zc+`64rR4(?KA4Z36_XPZe*B-`**Lk8(Z#^fC<e$+dB85n?vV7xL2R*1M+Ae?Hm56w
rO&n=%Y0?WMiVc{V8Q6BPe!}!*aY<rPNktLR{T8N%T&k+B{%%|V6ApG|

literal 0
HcmV?d00001

diff --git a/tests/docs/svg-conversion/with-rsvg-with-pdf/simple-svg.svg b/tests/docs/svg-conversion/with-rsvg-with-pdf/simple-svg.svg
new file mode 100644
index 0000000000..5cb8ca88bb
--- /dev/null
+++ b/tests/docs/svg-conversion/with-rsvg-with-pdf/simple-svg.svg
@@ -0,0 +1,3 @@
+<svg width="100" height="100" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="50" cy="50" r="50"/>
+</svg>
\ No newline at end of file
diff --git a/tests/docs/svg-conversion/with-rsvg/index.qmd b/tests/docs/svg-conversion/with-rsvg/index.qmd
new file mode 100644
index 0000000000..ff1ad53f9e
--- /dev/null
+++ b/tests/docs/svg-conversion/with-rsvg/index.qmd
@@ -0,0 +1,12 @@
+---
+title: "SVG to PDF with rsvg-convert"
+format:
+  pdf:
+    keep-tex: true
+---
+
+This test verifies that SVG images are correctly converted to PDF when rsvg-convert is available.
+
+The intermediate .tex file should show the converted PDF being included (not raw SVG).
+
+![Test SVG image](simple-svg.svg)
diff --git a/tests/docs/svg-conversion/with-rsvg/simple-svg.svg b/tests/docs/svg-conversion/with-rsvg/simple-svg.svg
new file mode 100644
index 0000000000..5cb8ca88bb
--- /dev/null
+++ b/tests/docs/svg-conversion/with-rsvg/simple-svg.svg
@@ -0,0 +1,3 @@
+<svg width="100" height="100" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="50" cy="50" r="50"/>
+</svg>
\ No newline at end of file
diff --git a/tests/docs/svg-conversion/without-rsvg-no-pdf.qmd b/tests/docs/svg-conversion/without-rsvg-no-pdf.qmd
new file mode 100644
index 0000000000..6f8d5f3b19
--- /dev/null
+++ b/tests/docs/svg-conversion/without-rsvg-no-pdf.qmd
@@ -0,0 +1,13 @@
+---
+title: "SVG without rsvg-convert (PDF missing - warning expected)"
+format: latex
+use-rsvg-convert: false
+---
+
+This test verifies that a warning is emitted when rsvg-convert is disabled and no pre-converted PDF exists.
+
+Using format: latex (not pdf) to generate .tex file without compiling, avoiding LaTeX/Inkscape dependencies.
+
+The filter should warn about missing PDF but still generate LaTeX output.
+
+![Test SVG image without pre-converted PDF](test-no-pdf.svg)
diff --git a/tests/smoke/render/render-pdf-svg-conversion.test.ts b/tests/smoke/render/render-pdf-svg-conversion.test.ts
new file mode 100644
index 0000000000..a983cffb34
--- /dev/null
+++ b/tests/smoke/render/render-pdf-svg-conversion.test.ts
@@ -0,0 +1,73 @@
+/*
+* render-pdf-svg-conversion.test.ts
+*
+* Copyright (C) 2020-2022 Posit Software, PBC
+*
+*/
+
+import { which } from "../../../src/core/path.ts";
+import { docs, outputForInput } from "../../utils.ts";
+import { ensureFileRegexMatches, ensureLatexFileRegexMatches, printsMessage } from "../../verify.ts";
+
+import { testRender } from "./render.ts";
+
+// Check for rsvg-convert availability (static for this test run)
+const hasRsvgConvert = await which("rsvg-convert") !== undefined;
+
+// Test 1: SVG to PDF with rsvg-convert available
+// Only runs if rsvg-convert is on PATH
+// Verifies that SVG is converted to PDF (not kept as SVG)Skipping SVG conversion for " .. path .. " because output file already exists:
+const test1Input = docs("svg-conversion/with-rsvg/index.qmd");
+const test1Output = outputForInput(test1Input, "pdf");
+testRender(test1Input, "pdf", false, [
+  ensureLatexFileRegexMatches(
+    test1Output.outputPath,
+    [
+      /\\includegraphics(\[.*?\])?\{[^}]*simple-svg\.pdf[^}]*\}/,  // Converted PDF included
+    ],
+    [
+      /\\includesvg/,  // Should NOT use includesvg (SVG was converted)
+    ],
+  ),
+], {
+  ignore: !hasRsvgConvert,
+});
+
+// Test 2: SVG to PDF without rsvg-convert, with pre-converted PDF
+// Should use existing PDF without warnings
+const test2Input = docs("svg-conversion/with-rsvg-with-pdf/index.qmd");
+const test2Output = outputForInput(test2Input, "pdf");
+testRender(test2Input, "pdf", false, [
+  ensureLatexFileRegexMatches(
+    test2Output.outputPath,
+    [
+      /\\includegraphics(\[.*?\])?\{[^}]*simple-svg\.pdf[^}]*\}/,  // Existing PDF included
+    ],
+    [
+      /\\includesvg/,  // Should NOT use includesvg (PDF was provided)
+    ],
+  ),
+  printsMessage({
+    level: "INFO",
+    regex: "Skipping SVG conversion .* because output file already exists"
+  }),
+]);
+
+// Test 3: SVG without rsvg-convert and no pre-converted PDF
+// Uses format: latex (not pdf) to generate .tex without compiling
+// Avoids LaTeX/Inkscape dependencies that would cause test to fail
+const test3Input = docs("svg-conversion/without-rsvg-no-pdf.qmd");
+const test3Output = outputForInput(test3Input, "latex");
+testRender(test3Input, "latex", true, [
+  printsMessage({
+    level: "INFO",
+    regex: "Skipping SVG conversion.*required PDF file does not exist"
+  }),
+  ensureFileRegexMatches(
+    test3Output.outputPath,
+    [
+      /\\usepackage(\[.*?\])?\{svg\}/,  // SVG package loaded
+      /\\includesvg(\[.*?\])?\{[^}]*test-no-pdf[^}]*\}/,  // includesvg command for our SVG
+    ],
+  ),
+]);

From 0b7f6615073bb966ec9cb5fcf57fda658576447c Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Tue, 18 Nov 2025 10:23:23 +0100
Subject: [PATCH 11/17] Add two more test to cover mermaid case in gfm

---
 .../2025/11/18/mermaid-gfm-default.qmd        | 37 ++++++++++++++++++
 .../smoke-all/2025/11/18/mermaid-gfm-svg.qmd  | 38 +++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 tests/docs/smoke-all/2025/11/18/mermaid-gfm-default.qmd
 create mode 100644 tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd

diff --git a/tests/docs/smoke-all/2025/11/18/mermaid-gfm-default.qmd b/tests/docs/smoke-all/2025/11/18/mermaid-gfm-default.qmd
new file mode 100644
index 0000000000..c5bad02b1f
--- /dev/null
+++ b/tests/docs/smoke-all/2025/11/18/mermaid-gfm-default.qmd
@@ -0,0 +1,37 @@
+---
+title: "GFM with default mermaid format"
+format: gfm
+_quarto:
+  tests:
+    gfm:
+      ensureFileRegexMatches:
+        - ['``` mermaid\s+graph']  # Verify raw mermaid code block is preserved (note space after ```)
+        - ['mermaid-figure-.*?\.svg']  # Should NOT have SVG files
+      printsMessage:
+        level: INFO
+        regex: 'Using mermaid-format'
+        negate: true  # Should NOT print any mermaid-format warnings
+---
+
+## GFM Default Mermaid Test
+
+This tests that GFM format uses GitHub's native mermaid code block support by default.
+
+```{mermaid}
+graph LR
+  A[Start] --> B{Decision}
+  B -->|Yes| C[Option 1]
+  B -->|No| D[Option 2]
+  C --> E[End]
+  D --> E
+```
+
+## Multi-line Labels Test
+
+GitHub's native mermaid renderer should handle this:
+
+```{mermaid}
+graph TD
+  A["This is a very long label<br/>with multiple lines<br/>of text content"] --> B["Another multi-line<br/>label here"]
+  B --> C[Short]
+```
diff --git a/tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd b/tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd
new file mode 100644
index 0000000000..0293578030
--- /dev/null
+++ b/tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd
@@ -0,0 +1,38 @@
+---
+title: "GFM with mermaid-format:svg"
+format: gfm
+mermaid-format: svg
+_quarto:
+  tests:
+    gfm:
+      ensureFileRegexMatches:
+        - ['img.*mermaid-figure-.*?\.svg']  # Verify markdown image link to SVG
+        - []
+      printsMessage:
+        level: INFO
+        regex: 'Using mermaid-format: svg'
+        negate: true  # Should NOT print warning for GFM
+---
+
+## GFM Mermaid Test
+
+This tests that GFM format correctly handles mermaid-format:svg without warnings.
+
+```{mermaid}
+graph LR
+  A[Start] --> B{Decision}
+  B -->|Yes| C[Option 1]
+  B -->|No| D[Option 2]
+  C --> E[End]
+  D --> E
+```
+
+## Multi-line Labels Test
+
+Testing that multi-line labels work (even though GFM doesn't have the clipping issue that LaTeX has):
+
+```{mermaid}
+graph TD
+  A["This is a very long label<br/>with multiple lines<br/>of text content"] --> B["Another multi-line<br/>label here"]
+  B --> C[Short]
+```

From a216295ccd249b176208056a85bfe21153b7728c Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Tue, 18 Nov 2025 10:40:41 +0100
Subject: [PATCH 12/17] Add `rsvg-convert` tooling for the specfic tests that
 need it

---
 .github/workflows/test-smokes.yml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/.github/workflows/test-smokes.yml b/.github/workflows/test-smokes.yml
index bbde6d158a..b50359571d 100644
--- a/.github/workflows/test-smokes.yml
+++ b/.github/workflows/test-smokes.yml
@@ -139,6 +139,13 @@ jobs:
           sudo apt-get install -y libharfbuzz-dev libfribidi-dev
           sudo apt-get install -y poppler-utils
 
+      - name: Install rsvg-convert for SVG conversion tests
+        # Only do it on linux runner, and only if we are running the relevant tests
+        if: runner.os == 'Linux' && contains(inputs.buckets, 'render-pdf-svg-conversion')
+        run: |
+          sudo apt-get update -y
+          sudo apt-get install -y librsvg2-bin
+
       - name: Restore R packages
         working-directory: tests
         run: |

From 4b13d3d4323717e344a76d8fa1ca381bc153be6d Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Tue, 18 Nov 2025 13:14:02 +0100
Subject: [PATCH 13/17] Add OS-specific test filtering for smoke-all tests

- Add skip-on-os metadata field (string or array of OS names)
- Rename skipTestOnCi() to skipTest() for broader scope
- Skip mermaid SVG tests on Linux (Puppeteer/Chrome environment issue)

Tests skipped on Linux (all timeout after 10 minutes):
- tests/docs/smoke-all/2025/11/10/13661.qmd (LaTeX)
- tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd (DOCX)
- tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd (GFM)

These tests pass on Windows. Linux support will be tracked in a
separate issue to investigate Puppeteer/headless Chrome setup.
---
 tests/docs/smoke-all/2025/11/10/13661.qmd     |  1 +
 .../smoke-all/2025/11/14/mermaid-svg-docx.qmd |  1 +
 .../smoke-all/2025/11/18/mermaid-gfm-svg.qmd  |  1 +
 tests/smoke/smoke-all.test.ts                 | 34 ++++++++++++++++---
 4 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/tests/docs/smoke-all/2025/11/10/13661.qmd b/tests/docs/smoke-all/2025/11/10/13661.qmd
index 01f4a86a32..6068bfb235 100644
--- a/tests/docs/smoke-all/2025/11/10/13661.qmd
+++ b/tests/docs/smoke-all/2025/11/10/13661.qmd
@@ -11,6 +11,7 @@ format:
     mermaid-format: svg
     use-rsvg-convert: false
 _quarto:
+  skip-on-os: linux
   tests:
     latex:
       printsMessage:
diff --git a/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd b/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
index 0dee48fc9a..79de29a4bd 100644
--- a/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
+++ b/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
@@ -4,6 +4,7 @@ format:
   docx:
     mermaid-format: svg
 _quarto:
+  skip-on-os: linux
   tests:
     docx:
       printsMessage:
diff --git a/tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd b/tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd
index 0293578030..7891e7ae01 100644
--- a/tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd
+++ b/tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd
@@ -3,6 +3,7 @@ title: "GFM with mermaid-format:svg"
 format: gfm
 mermaid-format: svg
 _quarto:
+  skip-on-os: linux
   tests:
     gfm:
       ensureFileRegexMatches:
diff --git a/tests/smoke/smoke-all.test.ts b/tests/smoke/smoke-all.test.ts
index 03efa8413f..90dcb05688 100644
--- a/tests/smoke/smoke-all.test.ts
+++ b/tests/smoke/smoke-all.test.ts
@@ -91,8 +91,29 @@ async function guessFormat(fileName: string): Promise<string[]> {
   return Array.from(formats);
 }
 
-function skipTestOnCi(metadata: Record<string, any>): boolean {
-  return runningInCI() && metadata["_quarto"]?.["tests-on-ci"] === false;
+function skipTest(metadata: Record<string, any>): boolean {
+  // Skip on CI if tests-on-ci: false
+  if (runningInCI() && metadata["_quarto"]?.["tests-on-ci"] === false) {
+    return true;
+  }
+
+  // Skip on specific OS if skip-on-os is set
+  const skipOnOs = metadata["_quarto"]?.["skip-on-os"];
+  if (skipOnOs !== undefined) {
+    const currentOs = Deno.build.os; // Returns: "linux" | "darwin" | "windows"
+
+    // Handle array of OSes
+    if (Array.isArray(skipOnOs)) {
+      return skipOnOs.includes(currentOs);
+    }
+
+    // Handle single OS string
+    if (typeof skipOnOs === "string") {
+      return skipOnOs === currentOs;
+    }
+  }
+
+  return false;
 }
 
 //deno-lint-ignore no-explicit-any
@@ -293,8 +314,13 @@ for (const { path: fileName } of files) {
     ? readYamlFromMarkdown(Deno.readTextFileSync(input))
     : readYamlFromMarkdown(await jupyterNotebookToMarkdown(input, false));
 
-  if (skipTestOnCi(metadata) === true) {
-    console.log(`Skipping tests for ${input} as tests-on-ci is false in metadata`);
+  if (skipTest(metadata) === true) {
+    // deno-lint-ignore no-explicit-any
+    const quartoMeta = metadata["_quarto"] as any;
+    const reason = quartoMeta?.["tests-on-ci"] === false
+      ? "tests-on-ci is false"
+      : `skip-on-os includes ${Deno.build.os}`;
+    console.log(`Skipping tests for ${input}: ${reason}`);
     continue;
   }
 

From 5eb38df62cbd477ac6201f448d3f8c74eba87a80 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Tue, 18 Nov 2025 13:15:02 +0100
Subject: [PATCH 14/17] Refactor skipTest to return reason string

Eliminates duplicate metadata retrieval by having skipTest() return
the skip reason (string) instead of boolean. Cleaner and more efficient.
---
 tests/smoke/smoke-all.test.ts | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/tests/smoke/smoke-all.test.ts b/tests/smoke/smoke-all.test.ts
index 90dcb05688..96054b90f1 100644
--- a/tests/smoke/smoke-all.test.ts
+++ b/tests/smoke/smoke-all.test.ts
@@ -91,29 +91,34 @@ async function guessFormat(fileName: string): Promise<string[]> {
   return Array.from(formats);
 }
 
-function skipTest(metadata: Record<string, any>): boolean {
+function skipTest(metadata: Record<string, any>): string | undefined {
+  // deno-lint-ignore no-explicit-any
+  const quartoMeta = metadata["_quarto"] as any;
+
   // Skip on CI if tests-on-ci: false
-  if (runningInCI() && metadata["_quarto"]?.["tests-on-ci"] === false) {
-    return true;
+  if (runningInCI() && quartoMeta?.["tests-on-ci"] === false) {
+    return "tests-on-ci is false";
   }
 
   // Skip on specific OS if skip-on-os is set
-  const skipOnOs = metadata["_quarto"]?.["skip-on-os"];
+  const skipOnOs = quartoMeta?.["skip-on-os"];
   if (skipOnOs !== undefined) {
     const currentOs = Deno.build.os; // Returns: "linux" | "darwin" | "windows"
 
     // Handle array of OSes
     if (Array.isArray(skipOnOs)) {
-      return skipOnOs.includes(currentOs);
+      if (skipOnOs.includes(currentOs)) {
+        return `skip-on-os includes ${currentOs}`;
+      }
     }
 
     // Handle single OS string
-    if (typeof skipOnOs === "string") {
-      return skipOnOs === currentOs;
+    if (typeof skipOnOs === "string" && skipOnOs === currentOs) {
+      return `skip-on-os is ${currentOs}`;
     }
   }
 
-  return false;
+  return undefined;
 }
 
 //deno-lint-ignore no-explicit-any
@@ -314,13 +319,9 @@ for (const { path: fileName } of files) {
     ? readYamlFromMarkdown(Deno.readTextFileSync(input))
     : readYamlFromMarkdown(await jupyterNotebookToMarkdown(input, false));
 
-  if (skipTest(metadata) === true) {
-    // deno-lint-ignore no-explicit-any
-    const quartoMeta = metadata["_quarto"] as any;
-    const reason = quartoMeta?.["tests-on-ci"] === false
-      ? "tests-on-ci is false"
-      : `skip-on-os includes ${Deno.build.os}`;
-    console.log(`Skipping tests for ${input}: ${reason}`);
+  const skipReason = skipTest(metadata);
+  if (skipReason !== undefined) {
+    console.log(`Skipping tests for ${input}: ${skipReason}`);
     continue;
   }
 

From 2b9510c45168e2e7425ee45d4003abfe35ed4836 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Tue, 18 Nov 2025 13:16:58 +0100
Subject: [PATCH 15/17] Use platform.ts os constant instead of Deno.build.os

Follows codebase pattern for OS detection.
---
 tests/smoke/smoke-all.test.ts | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/tests/smoke/smoke-all.test.ts b/tests/smoke/smoke-all.test.ts
index 96054b90f1..2cad74eb4d 100644
--- a/tests/smoke/smoke-all.test.ts
+++ b/tests/smoke/smoke-all.test.ts
@@ -11,6 +11,7 @@ import {
   initState,
   setInitializer,
 } from "../../src/core/lib/yaml-validation/state.ts";
+import { os } from "../../src/deno_ral/platform.ts";
 
 import { breakQuartoMd } from "../../src/core/lib/break-quarto-md.ts";
 import { parse } from "../../src/core/yaml.ts";
@@ -103,18 +104,16 @@ function skipTest(metadata: Record<string, any>): string | undefined {
   // Skip on specific OS if skip-on-os is set
   const skipOnOs = quartoMeta?.["skip-on-os"];
   if (skipOnOs !== undefined) {
-    const currentOs = Deno.build.os; // Returns: "linux" | "darwin" | "windows"
-
     // Handle array of OSes
     if (Array.isArray(skipOnOs)) {
-      if (skipOnOs.includes(currentOs)) {
-        return `skip-on-os includes ${currentOs}`;
+      if (skipOnOs.includes(os)) {
+        return `skip-on-os includes ${os}`;
       }
     }
 
     // Handle single OS string
-    if (typeof skipOnOs === "string" && skipOnOs === currentOs) {
-      return `skip-on-os is ${currentOs}`;
+    if (typeof skipOnOs === "string" && skipOnOs === os) {
+      return `skip-on-os is ${os}`;
     }
   }
 

From 85fec8487d86fa517b111652b60fe024c4cb62dc Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Tue, 18 Nov 2025 13:18:46 +0100
Subject: [PATCH 16/17] Use asArray utility to simplify OS filtering logic

Replaces separate string/array handling with asArray helper.
---
 tests/smoke/smoke-all.test.ts | 15 +++------------
 1 file changed, 3 insertions(+), 12 deletions(-)

diff --git a/tests/smoke/smoke-all.test.ts b/tests/smoke/smoke-all.test.ts
index 2cad74eb4d..08db81b302 100644
--- a/tests/smoke/smoke-all.test.ts
+++ b/tests/smoke/smoke-all.test.ts
@@ -12,6 +12,7 @@ import {
   setInitializer,
 } from "../../src/core/lib/yaml-validation/state.ts";
 import { os } from "../../src/deno_ral/platform.ts";
+import { asArray } from "../../src/core/array.ts";
 
 import { breakQuartoMd } from "../../src/core/lib/break-quarto-md.ts";
 import { parse } from "../../src/core/yaml.ts";
@@ -103,18 +104,8 @@ function skipTest(metadata: Record<string, any>): string | undefined {
 
   // Skip on specific OS if skip-on-os is set
   const skipOnOs = quartoMeta?.["skip-on-os"];
-  if (skipOnOs !== undefined) {
-    // Handle array of OSes
-    if (Array.isArray(skipOnOs)) {
-      if (skipOnOs.includes(os)) {
-        return `skip-on-os includes ${os}`;
-      }
-    }
-
-    // Handle single OS string
-    if (typeof skipOnOs === "string" && skipOnOs === os) {
-      return `skip-on-os is ${os}`;
-    }
+  if (skipOnOs !== undefined && asArray(skipOnOs).includes(os)) {
+    return `skip-on-os includes ${os}`;
   }
 
   return undefined;

From a0082262c46cb4181158d899fa54f77ef520fe82 Mon Sep 17 00:00:00 2001
From: Christophe Dervieux <christophe.dervieux@gmail.com>
Date: Tue, 18 Nov 2025 13:20:12 +0100
Subject: [PATCH 17/17] Document skip-on-os metadata in tests README

Adds documentation for the new skip-on-os metadata field that allows
skipping smoke-all tests on specific operating systems.
---
 tests/README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/tests/README.md b/tests/README.md
index 5a6c200169..99677e6d7b 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -120,6 +120,30 @@ $env:QUARTO_TESTS_NO_CONFIG=$true
 
 `docs/smoke-all/` is a specific folder to run some tests written directly within `.qmd`, `.md` or `.ipynb` files (but files starting with `_` will be ignored). They are run through the `smoke/smoke-all.tests.ts` script. To ease running smoke-all tests, `run-tests.sh` has a special behavior where it will run `./smoke/smoke-all.tests.ts` when passed a `.qmd`, `.md` or `.ipynb` file, not starting with `_`.
 
+##### Controlling test execution with metadata
+
+Smoke-all tests support metadata in the `_quarto` key to control when tests are run:
+
+**Skip tests on CI:**
+
+```yaml
+_quarto:
+  tests-on-ci: false
+```
+
+**Skip tests on specific operating systems:**
+
+```yaml
+_quarto:
+  skip-on-os: linux              # Skip only on Linux
+  skip-on-os: [linux, darwin]    # Skip on Linux and macOS
+  skip-on-os: windows             # Skip only on Windows
+```
+
+Valid OS values are: `linux`, `darwin` (macOS), `windows`
+
+This is useful when tests require platform-specific dependencies or have known platform-specific issues that need separate investigation.
+
 ```bash
 # run tests for all documents in docs/smoke-all/
 ./run-tests.sh smoke/smoke-all.tests.ts