Skip to content

Commit 64a810c

Browse files
cdervcderv
committed
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().
1 parent 6a8e07d commit 64a810c

File tree

4 files changed

+183
-19
lines changed

4 files changed

+183
-19
lines changed

‎src/core/handlers/mermaid.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -314,12 +314,12 @@ mermaid.initialize(${JSON.stringify(mermaidOpts)});
314314
isMarkdownOutput(handlerContext.options.format, ["gfm"]) ||
315315
!isJavascriptCompatible(handlerContext.options.format)
316316
) {
317-
// Emit info message for non-JS formats (excluding GFM which doesn't have the issue)
318-
if (!isMarkdownOutput(handlerContext.options.format, ["gfm"])) {
317+
// Emit info message for PDF/LaTeX formats (which require external tooling)
318+
if (isLatexOutput(handlerContext.options.format.pandoc)) {
319319
info(
320320
`Using mermaid-format: svg with ${
321-
handlerContext.options.format.pandoc.to ?? "non-HTML"
322-
} format. Note: diagrams with multi-line text labels may experience clipping. Consider using mermaid-format: png if issues occur.`,
321+
handlerContext.options.format.pandoc.to ?? "PDF"
322+
} format requires external tooling (rsvg-convert or Inkscape). Consider using mermaid-format: png if you encounter issues.`,
323323
);
324324
}
325325
const { sourceName, fullName } = handlerContext

‎tests/docs/manual/mermaid-svg-pdf-tooling.qmd‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
title: "Manual Test: Mermaid SVG with PDF - External Tooling"
3+
format:
4+
pdf:
5+
mermaid-format: svg
6+
keep-tex: true
7+
---
8+
9+
## Purpose
10+
11+
This document is for **manual testing** of mermaid-format:svg with PDF output,
12+
specifically to verify behavior with different external tooling configurations.
13+
14+
**Why manual?** Automated CI tests cannot easily verify:
15+
- Actual PDF generation with rsvg-convert
16+
- Inkscape fallback behavior
17+
- Platform-specific tooling issues (especially Windows)
18+
- Full conversion pipeline end-to-end
19+
20+
## Simple Diagram
21+
22+
```{mermaid}
23+
graph TD
24+
A[Start] --> B{Decision}
25+
B -->|Yes| C[Good]
26+
B -->|No| D[Bad]
27+
C --> E[End]
28+
D --> E
29+
```
30+
31+
## Multi-line Labels (Clipping Test)
32+
33+
This tests potential text clipping issues with multi-line labels:
34+
35+
```{mermaid}
36+
graph TD
37+
A["Line 1<br/>Line 2<br/>Line 3"] --> B["Another<br/>Multi<br/>Line<br/>Label"]
38+
B --> C["Final<br/>Node"]
39+
```
40+
41+
## Manual Testing Checklist
42+
43+
### Test 1: With rsvg-convert (Default)
44+
- [ ] Ensure `rsvg-convert` is on PATH
45+
- [ ] Run: `quarto render mermaid-svg-pdf-tooling.qmd`
46+
- [ ] Verify: INFO message includes "requires external tooling"
47+
- [ ] Verify: PDF generates successfully
48+
- [ ] Check `.tex` file for `\includesvg` commands
49+
- [ ] Verify: No script tags in LaTeX output
50+
- [ ] Open PDF: Diagrams render correctly
51+
52+
### Test 2: Without rsvg-convert
53+
- [ ] Remove rsvg-convert from PATH or rename binary temporarily
54+
- [ ] Run: `quarto render mermaid-svg-pdf-tooling.qmd`
55+
- [ ] Verify: INFO message about tooling requirement
56+
- [ ] Verify: Error about missing rsvg-convert
57+
- [ ] Expected behavior: Render fails with clear error
58+
59+
### Test 3: Inkscape Fallback (use-rsvg-convert: false)
60+
Create variant document with:
61+
```yaml
62+
format:
63+
pdf:
64+
mermaid-format: svg
65+
use-rsvg-convert: false
66+
pdf-engine-opt: ["-shell-escape"]
67+
keep-tex: true
68+
```
69+
70+
- [ ] Ensure Inkscape is installed
71+
- [ ] Run render with above config
72+
- [ ] Verify: INFO message about tooling
73+
- [ ] Verify: PDF generates via Inkscape (check logs)
74+
- [ ] Check `.tex` file: uses `\includesvg` with Inkscape
75+
- [ ] Open PDF: Diagrams render correctly
76+
77+
### Test 4: Windows-Specific
78+
- [ ] Test on Windows with rsvg-convert (if available via Scoop/other)
79+
- [ ] Test on Windows without rsvg-convert
80+
- [ ] Test Inkscape fallback on Windows
81+
- [ ] Document any Windows-specific issues
82+
83+
### Test 5: Comparison with PNG (Control)
84+
Create variant with `mermaid-format: png`:
85+
86+
- [ ] Run: `quarto render` with png format
87+
- [ ] Verify: NO warning about external tooling
88+
- [ ] Verify: PDF generates successfully
89+
- [ ] Quality comparison: SVG vs PNG in final PDF
90+
91+
## Expected Results Summary
92+
93+
| Scenario | Warning | PDF Generation | Notes |
94+
|----------|---------|----------------|-------|
95+
| rsvg-convert available | ✅ Yes | ✅ Success | Default path |
96+
| No rsvg-convert | ✅ Yes | ❌ Error | Clear error message |
97+
| Inkscape + shell-escape | ✅ Yes | ✅ Success | Fallback works |
98+
| PNG format | ❌ No | ✅ Success | No tooling needed |
99+
100+
## Platform-Specific Notes
101+
102+
### Linux/Mac
103+
- rsvg-convert typically available via package managers
104+
- `librsvg` package usually includes rsvg-convert
105+
- Inkscape widely available
106+
107+
### Windows
108+
- rsvg-convert NOT easily available (complex setup)
109+
- Can use Scoop: `scoop install rsvg-convert` (if r-bucket configured)
110+
- Inkscape available but requires shell-escape configuration
111+
- Most users should prefer PNG format on Windows
112+
113+
## Recording Results
114+
115+
After completing manual tests, document results in the beads issue notes field
116+
for quarto-cli-idi. Include:
117+
118+
- Platforms tested (OS, versions)
119+
- Which scenarios passed/failed
120+
- Any unexpected behavior
121+
- Screenshots if helpful
122+
- Recommendations for users
123+
124+
## See Also
125+
126+
- Automated test: `tests/docs/smoke-all/2025/11/10/13661.qmd`
127+
- DOCX test: `tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd`
128+
- Beads issue: quarto-cli-idi
129+
- GitHub issue: #13661

‎tests/docs/smoke-all/2025/11/10/13661.qmd‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,34 @@
11
---
2-
title: "Mermaid SVG format with Beamer (#13661)"
2+
title: "Mermaid SVG format with LaTeX - No script tags (#13661)"
3+
# Test strategy: Use format:latex with use-rsvg-convert:false to:
4+
# - Test mermaid-format:svg (the actual bug scenario)
5+
# - Generate .tex file without compiling PDF (avoids needing rsvg-convert/Inkscape in CI)
6+
# - Verify warning message about external tooling
7+
# - Verify LaTeX uses \includesvg (not \includegraphics)
8+
# - Verify NO HTML <script> tags in LaTeX output (the original bug)
39
format:
4-
beamer:
10+
latex:
511
mermaid-format: svg
6-
keep-tex: true
7-
pdf:
8-
mermaid-format: svg
9-
keep-tex: true
12+
use-rsvg-convert: false
1013
_quarto:
1114
tests:
12-
beamer:
13-
ensureLatexFileRegexMatches:
14-
- ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
15-
- ["<script[^>]*>", "mermaid-postprocess-shim"]
16-
pdf:
17-
ensureLatexFileRegexMatches:
15+
latex:
16+
printsMessage:
17+
level: INFO
18+
regex: 'requires external tooling'
19+
ensureFileRegexMatches:
1820
- ["\\\\includesvg(\\[.*?\\])?\\{[^}]*mermaid-figure-[^}]*\\}"]
1921
- ["<script[^>]*>", "mermaid-postprocess-shim"]
2022
---
2123

2224
## Test Diagram
2325

24-
Simple mermaid diagram to test SVG format with PDF/Beamer outputs:
26+
Simple mermaid diagram to test SVG format with LaTeX output.
27+
28+
**What this tests:**
29+
- Bug fix: HTML script tags should NOT appear in LaTeX output
30+
- Warning: Should emit INFO about requiring external tooling (rsvg-convert or Inkscape)
31+
- LaTeX structure: Should use `\includesvg` command for SVG files
2532

2633
```{mermaid}
2734
graph TD
@@ -31,5 +38,3 @@ graph TD
3138
C --> E[End]
3239
D --> E
3340
```
34-
35-
This should generate an SVG file and use LaTeX's `\includesvg` command without any HTML script tags.

‎tests/docs/smoke-all/2025/11/14/mermaid-svg-docx.qmd‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: "Mermaid SVG with DOCX - No tooling warning expected (#13661)"
3+
format:
4+
docx:
5+
mermaid-format: svg
6+
_quarto:
7+
tests:
8+
docx:
9+
printsMessage:
10+
level: INFO
11+
regex: 'requires external tooling'
12+
negate: true
13+
---
14+
15+
## Test Diagram
16+
17+
This tests that DOCX format with mermaid-format:svg does NOT emit
18+
the "requires external tooling" warning (since DOCX handles SVG natively).
19+
20+
```{mermaid}
21+
graph TD
22+
A[Start] --> B{Decision}
23+
B -->|Yes| C[Good]
24+
B -->|No| D[Bad]
25+
C --> E[End]
26+
D --> E
27+
```
28+
29+
Expected: No warning about external tooling (rsvg-convert/Inkscape).
30+
DOCX format handles SVG natively without requiring external converters.

0 commit comments

Comments
 (0)