Conditional content that should not be rendered produces error

[gustavdelius]

Bug description

When rendering to pdf, neither using ::: {.content-visible when-format="html"} nor using the chunk options include=knitr::is_html_output() and echo = false avoids an error about the fact that the code chunk, if rendered, would produce html output.

Steps to reproduce

Here is an example where the code block uses the vembedr package. Rendering the quarto document

---
title: "test"
format: pdf
---

Hello world

::: {.content-visible when-format="html"}

```{r, include=knitr::is_html_output()}
#| echo: false
vembedr::embed_url("https://youtu.be/_AeywguOA0o")
```

:::

Expected behavior

The code block should be ignored for the pdf output

Actual behavior

An error:

==> quarto preview test.qmd --to pdf --no-watch-inputs --no-browse



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

Error: Functions that produce HTML output found in document targeting pdf output.
Please change the output type of this document to HTML.
If you're aiming to have some HTML widgets shown in non-HTML format as a screenshot,
please install webshot or webshot2 R package for knitr to do the screenshot, and configure it by looking at its documentation.
Alternatively, you can allow HTML output in non-HTML formats
by adding this option to the YAML front-matter of
your quarto file:

  prefer-html: true

Note however that the HTML output will not be visible in non-HTML formats.

Execution halted

Your environment

• IDE RStudio RStudio 2024.12.0+467
• Linux Mint 22

Quarto check output

Quarto 1.6.39
[✓] Checking environment information...
Quarto cache location: /home/gustav/.cache/quarto
[✓] Checking versions of quarto binary dependencies...
Pandoc version 3.4.0: OK
Dart Sass version 1.70.0: OK
Deno version 1.46.3: OK
Typst version 0.11.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
Version: 1.6.39
Path: /opt/quarto/bin

[✓] Checking tools....................OK
TinyTeX: v2024.12
Chromium: (not installed)

[✓] Checking LaTeX....................OK
Using: TinyTex
Path: /home/gustav/.TinyTeX/bin/x86_64-linux
Version: 2024

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

[✓] Checking Python 3 installation....OK
Version: 3.12.3
Path: /usr/bin/python3
Jupyter: (None)

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

[✓] Checking R installation...........OK
Version: 4.4.2
Path: /usr/lib/R
LibPaths:
- /home/gustav/R/x86_64-pc-linux-gnu-library/4.4
- /usr/local/lib/R/site-library
- /usr/lib/R/site-library
- /usr/lib/R/library
knitr: 1.49
rmarkdown: 2.29

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

[cderv]

neither using ::: {.content-visible when-format="html"}

Using content-visible class on a Div does not prevent the cell for rendering. This visible / non-visible logic will apply only after computation have happen.

nor using the chunk options include=knitr::is_html_output() and echo = false avoids an error about the fact that the code chunk, if rendered, would produce html output.

See option documentation: https://yihui.org/knitr/options/#package-options

• include = FALSE means output won't be included in the output, but it is still executed.
• echo = FALSE means that the source code cell won't be in output.

What you are looking for is eval = FALSE so that the code in the cell is not run on the condition.

---
title: "test"
format: pdf
---

Hello world

::: {.content-visible when-format="html"}

```{r}
#| eval: !expr knitr::is_html_output()
vembedr::embed_url("https://youtu.be/_AeywguOA0o")
```

:::

You could also just use an if clause on the cell

---
title: "test"
format: pdf
---

Hello world

::: {.content-visible when-format="html"}

```{r}
#| echo: false
if (knitr::is_html_output()) {
  vembedr::embed_url("https://youtu.be/_AeywguOA0o")
}
```

:::

Note about using vembedr in Quarto - we have a video shortcode (https://quarto.org/docs/authoring/videos.html) that should do the same and will avoid running R for this.

Hope it helps

[gustavdelius]

@cderv Thank you very much for that very helpful response.

I am still a bit confused why the include = FALSE, which, as you say, should prevent the code output from being included in the knitted output, does not also prevent the error. However that will be just some strangeness of knitr and not an issue for quarto.

[cderv]

I am still a bit confused why the include = FALSE, which, as you say, should prevent the code output from being included in the knitted output, does not also prevent the error.

include: false is equivalent to echo: false, eval: true and output: hide. Basically it means to run the code but do not show any output.

• echo: false => do not show the code source in the output format
• eval: false => do not evaluate the code content

We document include in Quarto (https://quarto.org/docs/reference/cells/cells-knitr.html#cell-output) as

include
Catch all for preventing any output (code or results) from being included in output.

It is meant to be use when code needs to be run but just be sure to hide anything in the output format.

Hope it is clearer.

[bastienchassagnol]

@gustavdelius I completely agree that the documentation on conditional formatting (see [Conditional Content](https://quarto.org/docs/authoring/conditional.html) and [Conditional Content and Cross-References](https://quarto.org/docs/authoring/cross-references-divs.html#conditional-content) for more details) is quite confusing when it comes to distinguishing between visible text output and actual execution.

I suggest adding a clear example demonstrating the use of executable scripts within conditional div formats. It would also be helpful to include a warning for programmers that the Div notation does not prevent a code cell from being executed, as:

"Visible/non-visible logic applies only after computation has occurred." from @cderv. Note that the error generated at first was the following #8717 when I did not execute conditional rendering, which is even more confusing.

@cderv, a question for you: The solution you mentioned works well when using a single computation engine (e.g., knitr). What would be the best approach when mixing Jupyter and knitr engines?

@gustavdelius I've attached a test.txt file with a more complex example^[Just change the file extension to qmd, as this format is not allowed for uploading on Github issues] that combines conditional rendering execution with conditional output. Specifically, it generates a reactable table for html output and a flextable for docx or pdf outputs, while maintaining a common cross-reference for the generated table. I hope this helps with more advanced use cases!

test.txt

[mcanouil]

The solution you mentioned works well when using a single computation engine (e.g., knitr). What would be the best approach when mixing Jupyter and knitr engines?

There are no multiple engines documents.
If you want to use multiple languages, they have to be supported by the engine (/kernel) of your choosing.
Use Jupyter/Python with rpy2 for example to execute R code.
Use knitr with reticulate to execute Python code.

Pasting code in a code block is fine and better for accessibility. You don't need to upload/attach files.

[mcanouil]

For reference, the actual feature request for conditional execution:

• Conditional Chunk Execution #3260

[cderv]

The solution you mentioned works well when using a single computation engine (e.g., knitr). What would be the best approach when mixing Jupyter and knitr engines?

I will assume here you meen a Quarto project with knitr engine, and other doc with Jupyter engine. If not see reply above #11724 (comment)

See this trick to use inline Python evaluation to wrap some content to be hidden in output or not

• Conditional chunk for python quarto docs #12026 (comment)

If your question is about conditional evaluation of cell with jupyter, then require using the if logic I shared for R cells too.

We need to expose more information available as env var maybe to be really useful
Not there yet but on the list:

• communicate format output to all engines  #2216

So for now, as long as you make sure the evaluation does not error, you can use content hidden trick to conditional show the output, or use when-format or other conditional quarto already provide.

Thanks for sharing usecases, we'll make that better in the future

[bastienchassagnol]

The solution you mentioned works well when using a single computation engine (e.g., knitr). What would be the best approach when mixing Jupyter and knitr engines?

@cderv Thanks for sharing all these valuable resources, and I do think that enhancement feature suggested in issue #2216 is definitely interesting to look at 👍 .