Adding Supplementary figures via embed shortcode

[jestupinanm]

Description

Hello Quarto team

I have been trying to use the custom reference and embed features to write a manuscript with supplementary figures. Perhaps the way I am trying is not the intended one, as I am getting an incorrect rendering of my document

here a small example

in main.qmd

---
title: "Supplementary figures"
author: "Juan"
format: html
crossref: 
  custom: 
    - kind: float
      key: suppfig
      latex-env: suppfig
      reference-prefix: Figure S
      space-before-numbering: false
      latex-list-of-description: Supplementary Figure
---

This is an embedded figure from a code chunk

{{< embed notebook.qmd#fig-example >}}

but if I use a div, it is loaded as a subfigure (note the *(a)*)

::: {#suppfig-example}
{{< embed notebook.qmd#fig-example >}}
:::

in notebook.qmd

---
title: "notebook"
format: html
---

```{r}
#| label: fig-example
#| fig-cap: "this is an example figure"

x <- seq(1,10, 0.05)
plot(x, sin(x)+cos(x^2), type = "l")
```

when rendering to html, I obtain this at the end of my document

note the (a) placed below, and below it it is the caption for Figure S1. It seems the embedded figure is loaded as a subfigure, while the actual suppfig caption is empty.

Additionally, rendering the document to pdf gives me this error

Rendering PDF
running lualatex - 1
  This is LuaHBTeX, Version 1.22.0 (TeX Live 2025) 
   restricted system commands enabled.
  
updating tlmgr

updating existing packages
ERROR: 
compilation failed- error
Package caption Error: Undefined counter `subsuppfig'.

See the caption package documentation for explanation.
Type  H <return>  for immediate help.
 ...                                              
                                                  
l.209 \subcaption
               {\label{fig-example}this is an example figure}


see test.log for more information.
WARN: Error encountered when rendering files

Looking at the generated tex, I obtain this

% I did not copy the front matter to make it more readable

\begin{document}
\maketitle


This is an embedded figure from a code chunk

\begin{figure}

\centering{

\pandocbounded{\includegraphics[keepaspectratio]{test_files/figure-latex/notebook-fig-example-output-1.png}}

}

\caption{\label{fig-example}this is an example figure}

\end{figure}%

but if I use a div, it is loaded as a subfigure (note the \emph{(a)})

\begin{suppfig}

\centering{

\centering{

\pandocbounded{\includegraphics[keepaspectratio]{test_files/figure-latex/notebook-fig-example-output-1.png}}

}

\subcaption{\label{fig-example}this is an example figure}

}

\caption{\label{suppfig-example}}

\end{suppfig}%




\end{document}

---

again, I am not sure if this would be the intended way to use supplementary figures using an embed shortcode, so if there is another better way please let me know!

thank you!

quarto check

Quarto 1.8.25
[>] Checking environment information...
      Quarto cache location: C:\Users\User\AppData\Local\quarto
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.6.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.3.1: OK
      Typst version 0.13.0: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.8.25
      Path: C:\Users\User\AppData\Local\Programs\Quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: v2025.10
      Chromium: (not installed)

[>] Checking LaTeX....................OK
      Using: TinyTex
      Path: C:\Users\User\AppData\Roaming\TinyTeX\bin\windows\
      Version: 2025

[>] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
      Source: Windows Registry

[>] Checking basic markdown render....OK

[>] Checking Python 3 installation....OK
      Version: 3.9.0
      Path: C:/Program Files/Python39/python.exe
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with py -m pip install jupyter

[>] Checking R installation...........OK
      Version: 4.4.0
      Path: C:/PROGRA~1/R/R-44~1.0
      LibPaths:
        - C:/Users/User/AppData/Local/R/win-library/4.4
        - C:/Program Files/R/R-4.4.0/library
      knitr: 1.50
      rmarkdown: 2.29

[>] Checking Knitr engine render......OK

[mcanouil]

You are embedding a cross-reference (fig-example) inside another one (suppfig-example).

It's like writing the below, I don't think you even want that.

:::: {#suppfig-example}

:::: {#fig-example}
Text

Caption
:::

Caption
:::

I suggest to drop the fig- part and use something like:

:::: {#fig-example}
{{< embed notebook.qmd#example >}}
:::

:::: {#suppfig-example}
{{< embed notebook.qmd#example >}}
:::

[jestupinanm]

Hi!

thank you for the very fast answer. I tried your suggestion but I get now this error

processing file: main.qmd
                                                                                                      
output file: main.knit.md

Rendering qmd embeds
[1/1] notebook.qmd


processing file: notebook.qmd
                                                                                                            
output file: notebook.knit.md

ERROR: The cell example does not exist in notebook

this is how I tried to embed the figure

main.qmd

::: {#suppfig-example}
{{< embed notebook.qmd#example >}}

caption of the supplementary figure
:::

notebook.qmd

::: {#example}
```{r}
#| echo: false
x <- seq(1,10, 0.05)
plot(x, sin(x)+cos(x^2), type = "l")
```
:::

Also when I try to define the label in the code chunk instead, giving the same error

```{r}
#| label: example
#| echo: false

x <- seq(1,10, 0.05)
plot(x, sin(x)+cos(x^2), type = "l")
```

it seems I can not embed the figure if I don't use the prefix fig- in the label. Could this maybe be a limitation of the knitr engine?

To expand a bit, reading the examples in the embed guide, it is possible, using the jupyter engine, to give Tags to code cells and use them for embedding. However, tags haven't been implemented in the knitr engine and only labels can be used, as far as I understand

[mcanouil]

it seems I can not embed the figure if I don't use the prefix fig- in the label. Could this maybe be a limitation of the knitr engine?

The embed shortcode is agnostic but it is known to have issues with the knitr engine.

I don't think "tag" is the issue here.

[mcanouil]

The following works for R and Python.
The second embedding does not have the "source" link, but it works.

---
title: "Reproducible Quarto Document"
format: html
figure-captions:
  plot: "This is a plot generated from an embedded code cell."
crossref: 
  custom: 
    - kind: float
      key: suppfig
      latex-env: suppfig
      reference-prefix: Figure S
      space-before-numbering: false
      latex-list-of-description: Supplementary Figure
---

:::: {#fig-plot}
{{< embed cell.qmd#plot >}}

{{< meta figure-captions.plot >}}
:::


:::: {#suppfig-plot}
{{< embed cell.qmd#plot >}}

{{< meta figure-captions.plot >}}
:::

With cell.qmd:

R	Python
--- engine: knitr --- ```{r} #| label: plot plot(1) ```	--- engine: jupyter jupyter: python3 --- ```{python} # | label: plot import matplotlib.pyplot as plt x = [*range(10)] plt.plot(x, x) plt.show() ```

[jestupinanm]

It seems the error appears when I have also the echo: false option in the cell.qmd code chunk. Setting other options like fig-width or fig-height don't produce the error, and the embedding still shows those properties.
I guess for now I can just leave that out

Thanks again!

[mcanouil]

It seems to be an issue only when using echo: false at code cell level.

edit: Project/document level echo is ignored in the case of embedding.

You can set this at project/document level instead and enable echo: true only when needed.

---
execute:
  echo: false
---

• embed shortcode requires knitr engine cells to have echo: true (at cell level) #13735