Merge pull request #1830 from quarto-dev/sync-1829-to-prerelease

Author: cderv

docs/authoring/diagrams.qmd

@@ -200,6 +200,18 @@ format:
 
 Valid values for `mermaid-format` include `js`, `png`, and `svg`,
 
+::: callout-warning
+## SVG Format Limitations with PDF Output through LaTeX
+
+When rendering to LaTeX-based formats, `mermaid-format: svg` requires additional tooling and may have rendering issues:
+
+- **Requires installation:** `rsvg-convert` or `inkscape` must be available in your system PATH for Quarto to convert SVG to PDF to include in LaTeX.
+- **Potential rendering issues:** Text clipping in diagrams with multi-line labels
+- **Recommended:** Keep default `mermaid-format: png` for PDF output with LaTeX.
+
+For more details, including installation instructions and Inkscape configuration, see [SVG Images](/docs/output-formats/pdf-basics.qmd#svg-images).
+:::
+
 ## Mermaid Themes {#mermaid-theming}
 
 {{< include _mermaid-theming.qmd >}}

docs/output-formats/pdf-basics.qmd

@@ -214,7 +214,71 @@ With fonts with appropriate support, Greek symbols render correctly in headings,
 ![Greek symbols in a rendered PDF](images/pdf-unicode-greek.png){.border fig-alt="Screenshot of at PDF displaying the Greek symbol alpha in a heading, main text and code cell."}
 
 
- 
+## SVG Images {#svg-images}
+
+### Using `rsvg-convert` to convert to PDF
+
+Quarto supports rendering of PDF documents that include SVG files, automatically converting them to PDF images if `rsvg-convert` is available on the system path during rendering.
+
+You can learn more about installing `librsvg`{spellcheck="false"} (which provides `rsvg-convert`{spellcheck="false"}), see <https://wiki.gnome.org/Projects/LibRsvg>. To install on specific platforms:
+
+-   On MacOS, use Homebrew: `brew install librsvg`{spellcheck="false"}
+-   On Linux, tarballs available at: <https://download.gnome.org/sources/librsvg/>
+-   On Windows, install using chocolatey: `choco install rsvg-convert`{spellcheck="false"} or using Scoop:
+    
+    ````powershell
+    # scoop bucket add r-bucket https://github.com/cderv/r-bucket.git
+    scoop install rsvg-convert
+    ````
+
+### Alternative: Using Inkscape
+
+If you prefer to use Inkscape instead of `rsvg-convert`, you can disable the default conversion by setting `use-rsvg-convert: false`. This will use the [SVG LaTeX package](https://ctan.org/pkg/svg) to include the svg using `\includesvg{}` which uses Inkscape to convert to PDF. This requires some configuration to opt-in:
+
+```yaml
+format:
+  pdf:
+    use-rsvg-convert: false
+    pdf-engine-opts: ["-shell-escape"]
+```
+
+Note that this configuration requires:
+
+- Inkscape to be installed and available on your system PATH
+- The `-shell-escape` option for your LaTeX engine to allow execution of external programs
+- The SVG LaTeX package (automatically included by Quarto)
+
+### Platform Considerations
+
+The availability and ease of installation for SVG conversion tools varies by platform:
+
+- **Linux/macOS:** `rsvg-convert` is typically available through package managers (`librsvg` package). This is the recommended approach for these platforms.
+- **Windows:** Installing `rsvg-convert` is more challenging. While it can be installed via Scoop (as shown above), most Windows users should consider using PNG format for diagrams rather than SVG.
+- **Inkscape:** Available cross-platform but requires the `-shell-escape` configuration. Consider using this only when you specifically need Inkscape's rendering capabilities.
+
+For diagram formats, PNG is generally recommended for best compatibility and ease of use. See the @nte-svg-diagram below for more details.
+
+::: {#nte-svg-diagram .callout-note}
+## SVG Format for Diagrams
+
+When using Mermaid or Graphviz diagrams in PDF documents, the default PNG format is recommended. While SVG output is possible with `mermaid-format: svg`, it requires external tooling:
+
+- `rsvg-convert` (default) - See [installation instructions](#svg-images) above
+- Inkscape (alternative) - Requires `use-rsvg-convert: false` and `-shell-escape` configuration
+
+SVG format may also have rendering issues such as text clipping in diagrams with multi-line labels. For most users, PNG format provides better compatibility and ease of use. See [Diagrams](/docs/authoring/diagrams.qmd#mermaid-formats) for more information.
+:::
+
+## Remote Images
+
+You can reference remote images directly using URLs:
+
+```markdown
+![Penguins](https://example.com/images/penguins.png)
+```
+
+Images are automatically downloaded during rendering and embedded in the PDF.
+
 ## Citations
 
 {{< include _pdf-citations.md >}}

docs/prerelease/1.3/pdf.qmd

@@ -3,6 +3,17 @@ title: PDF Format Improvements
 search: true
 ---
 
+::: callout-note
+## Content Moved
+
+The SVG and Remote Images content from this page has been migrated to the main documentation:
+
+- [SVG Images](/docs/output-formats/pdf-basics.qmd#svg-images)
+- [Remote Images](/docs/output-formats/pdf-basics.qmd#remote-images)
+
+This page is retained for historical reference.
+:::
+
 {{< include /docs/_require-1.3.qmd >}}
 
 ## SVG Images