From 66080ff19b6764d05f0bc4253fdbaae038c632f8 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 18 Nov 2025 18:44:50 +0100 Subject: [PATCH 01/10] Move highlight to main doc about pdf images from svg --- docs/output-formats/pdf-basics.qmd | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/output-formats/pdf-basics.qmd b/docs/output-formats/pdf-basics.qmd index d267851fe..a298da2f1 100644 --- a/docs/output-formats/pdf-basics.qmd +++ b/docs/output-formats/pdf-basics.qmd @@ -214,7 +214,26 @@ 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} + +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 . To install on specific platforms: + +- On MacOS, use Homebrew: `brew install librsvg`{spellcheck="false"} +- On Linux, tarballs available at: +- On Windows, install using chocolatey: `choco install rsvg-convert`{spellcheck="false"} + +::: 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 `rsvg-convert` and may have rendering issues such as text clipping in diagrams with multi-line labels. See [Diagrams](/docs/authoring/diagrams.qmd#mermaid-formats) for more information. +::: + +## Remote Images + +When rendering PDFs, Quarto automatically fetches remote image references and properly embeds them within the PDF. + ## Citations {{< include _pdf-citations.md >}} From 2994abeab06912044091b1de4c6871e4e160c34c Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 18 Nov 2025 18:45:08 +0100 Subject: [PATCH 02/10] Add callout to original highlight page --- docs/prerelease/1.3/pdf.qmd | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/prerelease/1.3/pdf.qmd b/docs/prerelease/1.3/pdf.qmd index 51b84b918..79108acc3 100644 --- a/docs/prerelease/1.3/pdf.qmd +++ b/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#svg-images) + +This page is retained for historical reference. +::: + {{< include /docs/_require-1.3.qmd >}} ## SVG Images From 010b114e7e5b2728ddae3d0a50efab597344dffd Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 18 Nov 2025 18:45:24 +0100 Subject: [PATCH 03/10] Add a callout in diagram about setting SVG format for PDF --- docs/authoring/diagrams.qmd | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/authoring/diagrams.qmd b/docs/authoring/diagrams.qmd index 712007803..f9cb3daca 100644 --- a/docs/authoring/diagrams.qmd +++ b/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 + +When rendering to PDF or LaTeX-based formats, `mermaid-format: svg` requires additional tooling and may have rendering issues: + +- **Requires installation:** `rsvg-convert` must be available in your system PATH +- **Potential rendering issues:** Text clipping in diagrams with multi-line labels +- **Recommended:** Use default `mermaid-format: png` for PDF output + +For installation instructions, see [SVG Images](/docs/output-formats/pdf-basics.qmd#svg-images). +::: + ## Mermaid Themes {#mermaid-theming} {{< include _mermaid-theming.qmd >}} From 72f1a77ddd1052a84b703ea62f5e66370f3ff8e7 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 18 Nov 2025 18:51:11 +0100 Subject: [PATCH 04/10] Also mention scoop r-bucket --- docs/output-formats/pdf-basics.qmd | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/output-formats/pdf-basics.qmd b/docs/output-formats/pdf-basics.qmd index a298da2f1..70d72f1df 100644 --- a/docs/output-formats/pdf-basics.qmd +++ b/docs/output-formats/pdf-basics.qmd @@ -222,7 +222,11 @@ You can learn more about installing `librsvg`{spellcheck="false"} (which provide - On MacOS, use Homebrew: `brew install librsvg`{spellcheck="false"} - On Linux, tarballs available at: -- On Windows, install using chocolatey: `choco install rsvg-convert`{spellcheck="false"} +- 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 + ```` ::: callout-note ## SVG Format for Diagrams From 3cdff0b981ca19f4cb3b659ee1cc55a2fc2c5acb Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 19 Nov 2025 12:38:24 +0100 Subject: [PATCH 05/10] make some edits to doc --- docs/authoring/diagrams.qmd | 10 +++++----- docs/output-formats/pdf-basics.qmd | 1 + 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/authoring/diagrams.qmd b/docs/authoring/diagrams.qmd index f9cb3daca..fef8f8c56 100644 --- a/docs/authoring/diagrams.qmd +++ b/docs/authoring/diagrams.qmd @@ -201,15 +201,15 @@ format: Valid values for `mermaid-format` include `js`, `png`, and `svg`, ::: callout-warning -## SVG Format Limitations with PDF Output +## SVG Format Limitations with PDF Output through LaTeX -When rendering to PDF or LaTeX-based formats, `mermaid-format: svg` requires additional tooling and may have rendering issues: +When rendering to LaTeX-based formats, `mermaid-format: svg` requires additional tooling and may have rendering issues: -- **Requires installation:** `rsvg-convert` must be available in your system PATH +- **Requires installation:** `rsvg-convert` 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:** Use default `mermaid-format: png` for PDF output +- **Recommended:** Keep default `mermaid-format: png` for PDF output with LaTeX. -For installation instructions, see [SVG Images](/docs/output-formats/pdf-basics.qmd#svg-images). +For more details, including installation instructions, see [SVG Images](/docs/output-formats/pdf-basics.qmd#svg-images). ::: ## Mermaid Themes {#mermaid-theming} diff --git a/docs/output-formats/pdf-basics.qmd b/docs/output-formats/pdf-basics.qmd index 70d72f1df..32199bb19 100644 --- a/docs/output-formats/pdf-basics.qmd +++ b/docs/output-formats/pdf-basics.qmd @@ -223,6 +223,7 @@ You can learn more about installing `librsvg`{spellcheck="false"} (which provide - On MacOS, use Homebrew: `brew install librsvg`{spellcheck="false"} - On Linux, tarballs available at: - 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 From b3d58d4b0936ebfa092c98788a7cfd41383fb1f6 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 19 Nov 2025 12:47:59 +0100 Subject: [PATCH 06/10] Add inkscape usage and configuration when using LaTeX --- docs/authoring/diagrams.qmd | 4 ++-- docs/output-formats/pdf-basics.qmd | 36 ++++++++++++++++++++++++++++-- 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/docs/authoring/diagrams.qmd b/docs/authoring/diagrams.qmd index fef8f8c56..73e751c66 100644 --- a/docs/authoring/diagrams.qmd +++ b/docs/authoring/diagrams.qmd @@ -205,11 +205,11 @@ Valid values for `mermaid-format` include `js`, `png`, and `svg`, When rendering to LaTeX-based formats, `mermaid-format: svg` requires additional tooling and may have rendering issues: -- **Requires installation:** `rsvg-convert` must be available in your system PATH for Quarto to convert SVG to PDF to include in LaTeX. +- **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, see [SVG Images](/docs/output-formats/pdf-basics.qmd#svg-images). +For more details, including installation instructions and Inkscape configuration, see [SVG Images](/docs/output-formats/pdf-basics.qmd#svg-images). ::: ## Mermaid Themes {#mermaid-theming} diff --git a/docs/output-formats/pdf-basics.qmd b/docs/output-formats/pdf-basics.qmd index 32199bb19..86eaef896 100644 --- a/docs/output-formats/pdf-basics.qmd +++ b/docs/output-formats/pdf-basics.qmd @@ -229,10 +229,42 @@ You can learn more about installing `librsvg`{spellcheck="false"} (which provide scoop install rsvg-convert ```` -::: callout-note +### 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 @nt-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 `rsvg-convert` and may have rendering issues such as text clipping in diagrams with multi-line labels. See [Diagrams](/docs/authoring/diagrams.qmd#mermaid-formats) for more information. +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 From 1564b18b1119eec5948d432aa298fcca3867c8c1 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 19 Nov 2025 13:03:17 +0100 Subject: [PATCH 07/10] Add a new subtitle --- docs/output-formats/pdf-basics.qmd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/output-formats/pdf-basics.qmd b/docs/output-formats/pdf-basics.qmd index 86eaef896..ee098c36a 100644 --- a/docs/output-formats/pdf-basics.qmd +++ b/docs/output-formats/pdf-basics.qmd @@ -216,6 +216,8 @@ With fonts with appropriate support, Greek symbols render correctly in headings, ## 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 . To install on specific platforms: From ae0e19424846e22c8cc74d71557a2c7428a3abf9 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 19 Nov 2025 13:04:09 +0100 Subject: [PATCH 08/10] Correct reference ID --- docs/output-formats/pdf-basics.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/output-formats/pdf-basics.qmd b/docs/output-formats/pdf-basics.qmd index ee098c36a..b8a291f39 100644 --- a/docs/output-formats/pdf-basics.qmd +++ b/docs/output-formats/pdf-basics.qmd @@ -256,7 +256,7 @@ The availability and ease of installation for SVG conversion tools varies by pla - **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 @nt-svg-diagram below for more details. +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 From cba0b4fb517259ef24bbd5bc859730af74199e26 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 19 Nov 2025 13:05:11 +0100 Subject: [PATCH 09/10] Correct link --- docs/prerelease/1.3/pdf.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/prerelease/1.3/pdf.qmd b/docs/prerelease/1.3/pdf.qmd index 79108acc3..f372866e8 100644 --- a/docs/prerelease/1.3/pdf.qmd +++ b/docs/prerelease/1.3/pdf.qmd @@ -9,7 +9,7 @@ search: true 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#svg-images) +- [Remote Images](/docs/output-formats/pdf-basics.qmd#remote-images) This page is retained for historical reference. ::: From 36a43c2d742ead6d99690a963a1a62fa422bfd23 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 19 Nov 2025 14:13:59 +0100 Subject: [PATCH 10/10] Give more details about remote image download --- docs/output-formats/pdf-basics.qmd | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/output-formats/pdf-basics.qmd b/docs/output-formats/pdf-basics.qmd index b8a291f39..87a0f66c7 100644 --- a/docs/output-formats/pdf-basics.qmd +++ b/docs/output-formats/pdf-basics.qmd @@ -271,7 +271,13 @@ SVG format may also have rendering issues such as text clipping in diagrams with ## Remote Images -When rendering PDFs, Quarto automatically fetches remote image references and properly embeds them within the PDF. +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