diff --git a/.github/workflows/test-smokes.yml b/.github/workflows/test-smokes.yml
index bbde6d158ad..b50359571df 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: |
diff --git a/news/changelog-1.9.md b/news/changelog-1.9.md
index be96d684a8c..da6de3c010c 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
diff --git a/src/core/handlers/mermaid.ts b/src/core/handlers/mermaid.ts
index edb5484bc0d..8bef0cd1846 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,29 @@ 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"])) {
+          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(
             "mermaid-figure-",
@@ -323,6 +345,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,
diff --git a/src/resources/filters/quarto-post/pdf-images.lua b/src/resources/filters/quarto-post/pdf-images.lua
index fc21e3e0026..daf8a3e5fa7 100644
--- a/src/resources/filters/quarto-post/pdf-images.lua
+++ b/src/resources/filters/quarto-post/pdf-images.lua
@@ -36,7 +36,8 @@ 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)
+      return nil
     else
       image.src = output
       return image
diff --git a/tests/README.md b/tests/README.md
index 5a6c200169f..99677e6d7b5 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
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 00000000000..593b364ac38
--- /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/2024/01/26/issue-8299-1.qmd b/tests/docs/smoke-all/2024/01/26/issue-8299-1.qmd
deleted file mode 100644
index b4227a1458b..00000000000
--- 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 d2b57dd2f3f..00000000000
--- 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/smoke-all/2025/11/10/13661.qmd b/tests/docs/smoke-all/2025/11/10/13661.qmd
new file mode 100644
index 00000000000..6068bfb2359
--- /dev/null
+++ b/tests/docs/smoke-all/2025/11/10/13661.qmd
@@ -0,0 +1,41 @@
+---
+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:
+  latex:
+    mermaid-format: svg
+    use-rsvg-convert: false
+_quarto:
+  skip-on-os: linux
+  tests:
+    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 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
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Good]
+    B -->|No| D[Bad]
+    C --> E[End]
+    D --> E
+```
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 00000000000..79de29a4bd9
--- /dev/null
+++ b/tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd
@@ -0,0 +1,30 @@
+---
+title: "Mermaid SVG with DOCX - Clipping warning expected (#13661)"
+format:
+  docx:
+    mermaid-format: svg
+_quarto:
+  skip-on-os: linux
+  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).
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 00000000000..c5bad02b1f6
--- /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 00000000000..7891e7ae013
--- /dev/null
+++ b/tests/docs/smoke-all/2025/11/18/mermaid-gfm-svg.qmd
@@ -0,0 +1,39 @@
+---
+title: "GFM with mermaid-format:svg"
+format: gfm
+mermaid-format: svg
+_quarto:
+  skip-on-os: linux
+  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]
+```
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 00000000000..d50c436353c
--- /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 00000000000..e227d8c1c47
--- /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 00000000000..d903d28a451
Binary files /dev/null and b/tests/docs/svg-conversion/with-rsvg-with-pdf/simple-svg.pdf differ
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 00000000000..5cb8ca88bb6
--- /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 00000000000..ff1ad53f9e0
--- /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 00000000000..5cb8ca88bb6
--- /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 00000000000..6f8d5f3b19c
--- /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 00000000000..a983cffb346
--- /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
+    ],
+  ),
+]);
diff --git a/tests/smoke/smoke-all.test.ts b/tests/smoke/smoke-all.test.ts
index 03efa8413f3..08db81b302f 100644
--- a/tests/smoke/smoke-all.test.ts
+++ b/tests/smoke/smoke-all.test.ts
@@ -11,6 +11,8 @@ import {
   initState,
   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";
@@ -91,8 +93,22 @@ 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>): string | undefined {
+  // deno-lint-ignore no-explicit-any
+  const quartoMeta = metadata["_quarto"] as any;
+
+  // Skip on CI if tests-on-ci: false
+  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 = quartoMeta?.["skip-on-os"];
+  if (skipOnOs !== undefined && asArray(skipOnOs).includes(os)) {
+    return `skip-on-os includes ${os}`;
+  }
+
+  return undefined;
 }
 
 //deno-lint-ignore no-explicit-any
@@ -293,8 +309,9 @@ 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`);
+  const skipReason = skipTest(metadata);
+  if (skipReason !== undefined) {
+    console.log(`Skipping tests for ${input}: ${skipReason}`);
     continue;
   }
 
diff --git a/tests/test.ts b/tests/test.ts
index 6390aea40e3..562b415246e 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