From ed125c4abb2f2ecf34309d53baf21f2ff38f4218 Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 16:22:20 +0200 Subject: [PATCH 01/10] Document conditional execution in execution-options.qmd Adds a section linking to docs/advanced/quarto-execute-info.qmd so users browsing execution options discover the format-aware QUARTO_EXECUTE_INFO env var. Part of #13514. --- docs/computations/execution-options.qmd | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/computations/execution-options.qmd b/docs/computations/execution-options.qmd index 72cff721b8..dc6bd0d2d0 100644 --- a/docs/computations/execution-options.qmd +++ b/docs/computations/execution-options.qmd @@ -498,3 +498,11 @@ echo "foo" ```` Note that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document + +## Conditional Execution + +In some cases you want code execution itself — not just visibility of its output — to depend on the active output format. For example, when rendering to PDF you may want to skip a cell that loads an interactive HTML widget, rather than execute it and hide the result. + +Quarto exposes the current rendering context in the `QUARTO_EXECUTE_INFO` environment variable. Cells can read this variable to detect the active format and branch accordingly. See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the full JSON schema and examples in R, Python, and Julia. + +This complements format-based [conditional content](/docs/authoring/conditional.qmd), which controls visibility of *already-executed* output. `QUARTO_EXECUTE_INFO` lets you skip work, choose a different code path, or load a different library before any output is produced. From f0d74f6624f72c26bb47c053c89b6470b134b49c Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 16:26:36 +0200 Subject: [PATCH 02/10] Add Conditional Execution section to Using R Points readers of computations/r.qmd at QUARTO_EXECUTE_INFO so they can branch on output format. Mirrors the additions for Python and Julia. Part of #13514. --- docs/computations/r.qmd | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/computations/r.qmd b/docs/computations/r.qmd index 4559b946e9..ef59ef7305 100644 --- a/docs/computations/r.qmd +++ b/docs/computations/r.qmd @@ -156,6 +156,23 @@ airquality$TempC <- (5 / 9) * (airquality$Temp - 32) Unless you want to specify a cross-reference avoid using the [reserved cross-reference prefixes](/docs/authoring/cross-references.qmd#reserved-prefixes) for chunk labels. +## Conditional Execution + +To execute a cell only for certain output formats, read the [`QUARTO_EXECUTE_INFO`](/docs/advanced/quarto-execute-info.qmd) environment variable inside the cell: + +```` markdown +```{r} +info <- jsonlite::fromJSON(Sys.getenv("QUARTO_EXECUTE_INFO")) +is_html <- info$format$identifier$`base-format` == "html" + +if (is_html) { + # HTML-only code, e.g. an interactive widget +} +``` +```` + +This pairs well with [conditional content](/docs/authoring/conditional.qmd) when both visibility and execution should depend on format. See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the full JSON schema. + ## Output Formats {#output-formats} Another difference between R Markdown and Quarto is related to output formats. Quarto includes many more built in output formats (and many more options for customizing each format). Quarto also has native features for special project types like [Websites](/docs/websites/), [Books](/docs/books/), and [Blogs](/docs/websites/website-blog.qmd) (rather than relying on external packages). From e7f4fb54e13bf845570f663c74a606ca1ff4029e Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 16:32:08 +0200 Subject: [PATCH 03/10] Escape inner {{r}} cell marker in Conditional Execution example The {r} marker was unescaped inside a markdown verbatim block; Quarto would have treated it as an executable cell on render. Matches the {{r}} escape pattern used by the sibling Chunk Labels example in the same file. Part of #13514. --- docs/computations/r.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/computations/r.qmd b/docs/computations/r.qmd index ef59ef7305..260fa2adbd 100644 --- a/docs/computations/r.qmd +++ b/docs/computations/r.qmd @@ -161,7 +161,7 @@ Unless you want to specify a cross-reference avoid using the [reserved cross-ref To execute a cell only for certain output formats, read the [`QUARTO_EXECUTE_INFO`](/docs/advanced/quarto-execute-info.qmd) environment variable inside the cell: ```` markdown -```{r} +```{{r}} info <- jsonlite::fromJSON(Sys.getenv("QUARTO_EXECUTE_INFO")) is_html <- info$format$identifier$`base-format` == "html" From 38822bc457a27a4be30a25df1d266dcda916c89e Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 16:34:03 +0200 Subject: [PATCH 04/10] Add Conditional Execution section to Using Python Points readers of computations/python.qmd at QUARTO_EXECUTE_INFO so they can branch on output format. Mirrors the additions for R and Julia. Part of #13514. --- docs/computations/python.qmd | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/computations/python.qmd b/docs/computations/python.qmd index 76b55aa6a2..5b7dfef589 100644 --- a/docs/computations/python.qmd +++ b/docs/computations/python.qmd @@ -112,3 +112,25 @@ Note that this step is not required if you are merely using conda with Quarto. I ::: {{< include _jupyter-daemon.md >}} + +## Conditional Execution + +To execute a cell only for certain output formats, read the [`QUARTO_EXECUTE_INFO`](/docs/advanced/quarto-execute-info.qmd) environment variable inside the cell: + +```` markdown +```{{python}} +import json +import os + +with open(os.environ["QUARTO_EXECUTE_INFO"]) as f: + info = json.load(f) + +is_html = info["format"]["identifier"]["base-format"] == "html" + +if is_html: + # HTML-only code, e.g. an interactive widget + ... +``` +```` + +This pairs well with [conditional content](/docs/authoring/conditional.qmd) when both visibility and execution should depend on format. See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the full JSON schema. From fd2ad7dd720eccd68f6d639e7d063e15eab278ff Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 16:38:28 +0200 Subject: [PATCH 05/10] Add Conditional Execution section to Using Julia Points readers of computations/julia.qmd at QUARTO_EXECUTE_INFO so they can branch on output format. Mirrors the additions for R and Python. Part of #13514. --- docs/computations/julia.qmd | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/computations/julia.qmd b/docs/computations/julia.qmd index 0376d3afd9..17b2419d46 100644 --- a/docs/computations/julia.qmd +++ b/docs/computations/julia.qmd @@ -543,6 +543,25 @@ Please direct questions and requests regarding this functionality to the [QuartoNotebookRunner](https://github.com/PumasAI/QuartoNotebookRunner.jl) repository. +## Conditional Execution + +To execute a cell only for certain output formats, read the [`QUARTO_EXECUTE_INFO`](/docs/advanced/quarto-execute-info.qmd) environment variable inside the cell: + +```` markdown +```{{julia}} +using JSON + +info = JSON.parsefile(ENV["QUARTO_EXECUTE_INFO"]) +is_html = info["format"]["identifier"]["base-format"] == "html" + +if is_html + # HTML-only code, e.g. an interactive widget +end +``` +```` + +This pairs well with [conditional content](/docs/authoring/conditional.qmd) when both visibility and execution should depend on format. See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the full JSON schema. + # Using the `jupyter` engine ### Installation {#installation} From c509ec8897033e8e74b0d022b4043ebe91aa68e0 Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 16:42:00 +0200 Subject: [PATCH 06/10] Clarify conditional content vs conditional execution Markup-based .content-visible / .content-hidden hide output but do not skip execution. Adds a pointer section to QUARTO_EXECUTE_INFO for the execution-level case. Part of #13514. --- docs/authoring/conditional.qmd | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/authoring/conditional.qmd b/docs/authoring/conditional.qmd index 33b11cafb4..4645c54d26 100644 --- a/docs/authoring/conditional.qmd +++ b/docs/authoring/conditional.qmd @@ -112,4 +112,10 @@ path: ```` This feature is often useful alongside [project profiles](/docs/projects/profiles.qmd). -Different profiles can set different metadata values, and so can control the metadata used in conditional content. \ No newline at end of file +Different profiles can set different metadata values, and so can control the metadata used in conditional content. + +## Conditional Execution + +The `.content-visible` and `.content-hidden` classes control whether content is *shown* in the rendered output. They do **not** prevent the code in cells they wrap from executing. If you need to skip execution entirely based on the output format — for example, to avoid loading a package or calling a service that only makes sense for one format — have the cell itself check the `QUARTO_EXECUTE_INFO` environment variable. + +See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the JSON schema and examples in R, Python, and Julia. \ No newline at end of file From 5ec4fcf6b5493e51169ff313f2ceab2f40be6324 Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 16:45:40 +0200 Subject: [PATCH 07/10] Add trailing newline to conditional.qmd Pre-existing EOF lacked a terminal newline; appending Conditional Execution section preserved that. Aligns with other .qmd files in the repo. Part of #13514. --- docs/authoring/conditional.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/authoring/conditional.qmd b/docs/authoring/conditional.qmd index 4645c54d26..54927ae6f5 100644 --- a/docs/authoring/conditional.qmd +++ b/docs/authoring/conditional.qmd @@ -118,4 +118,4 @@ Different profiles can set different metadata values, and so can control the met The `.content-visible` and `.content-hidden` classes control whether content is *shown* in the rendered output. They do **not** prevent the code in cells they wrap from executing. If you need to skip execution entirely based on the output format — for example, to avoid loading a package or calling a service that only makes sense for one format — have the cell itself check the `QUARTO_EXECUTE_INFO` environment variable. -See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the JSON schema and examples in R, Python, and Julia. \ No newline at end of file +See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the JSON schema and examples in R, Python, and Julia. From 97093d8af31a4ae6f40c546b3e603b462c732b32 Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 16:47:13 +0200 Subject: [PATCH 08/10] Note conditional execution + profiles in cross-ref divs The conditional-content example in cross-references-divs.qmd hides one branch but still runs both. Adds two pointers: (1) QUARTO_EXECUTE_INFO for users who need to skip execution, (2) project profiles as another axis for content variation beyond output format. Both flagged in issue thread. Part of #13514. --- docs/authoring/cross-references-divs.qmd | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/authoring/cross-references-divs.qmd b/docs/authoring/cross-references-divs.qmd index 59dc99ab15..cd80888c5b 100644 --- a/docs/authoring/cross-references-divs.qmd +++ b/docs/authoring/cross-references-divs.qmd @@ -438,3 +438,7 @@ Scatterplot @fig-scatterplot ```` + +Note that `.content-visible` and `.content-hidden` only control output visibility — the code cells inside still execute. To skip execution entirely based on the output format, have the cell read the `QUARTO_EXECUTE_INFO` environment variable. See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for details. + +When the variation you need is broader than output format — for example, the same document rendered as a draft vs. a final, or for an internal vs. an external audience — [project profiles](/docs/projects/profiles.qmd) can set alternate metadata per profile that `.content-visible when-meta=...` reads. This gives you another axis for conditional content beyond `when-format`. From 76858f4ddce3b4e3e9468b58b90e3606269c96c4 Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 17:10:20 +0200 Subject: [PATCH 09/10] Extract shared visibility-vs-execution note to partial conditional.qmd and cross-references-divs.qmd both clarify that .content-visible / .content-hidden hide output but do not skip execution. The two paragraphs duplicated the same takeaway in slightly different words. Extract the single canonical version to docs/authoring/_visibility-vs-execution.md and include it from both pages. The project-profiles paragraph in cross-references-divs.qmd stays inline (specific to that page). Part of #13514. --- docs/authoring/_visibility-vs-execution.md | 1 + docs/authoring/conditional.qmd | 4 +--- docs/authoring/cross-references-divs.qmd | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) create mode 100644 docs/authoring/_visibility-vs-execution.md diff --git a/docs/authoring/_visibility-vs-execution.md b/docs/authoring/_visibility-vs-execution.md new file mode 100644 index 0000000000..fdace97557 --- /dev/null +++ b/docs/authoring/_visibility-vs-execution.md @@ -0,0 +1 @@ +The `.content-visible` and `.content-hidden` classes control whether content is *shown* in the rendered output. They do **not** prevent the code in cells they wrap from executing. If you need to skip execution entirely based on the output format — for example, to avoid loading a package or calling a service that only makes sense for one format — have the cell itself read the `QUARTO_EXECUTE_INFO` environment variable. See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the JSON schema and examples in R, Python, and Julia. diff --git a/docs/authoring/conditional.qmd b/docs/authoring/conditional.qmd index 54927ae6f5..3ba08f8305 100644 --- a/docs/authoring/conditional.qmd +++ b/docs/authoring/conditional.qmd @@ -116,6 +116,4 @@ Different profiles can set different metadata values, and so can control the met ## Conditional Execution -The `.content-visible` and `.content-hidden` classes control whether content is *shown* in the rendered output. They do **not** prevent the code in cells they wrap from executing. If you need to skip execution entirely based on the output format — for example, to avoid loading a package or calling a service that only makes sense for one format — have the cell itself check the `QUARTO_EXECUTE_INFO` environment variable. - -See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the JSON schema and examples in R, Python, and Julia. +{{< include _visibility-vs-execution.md >}} diff --git a/docs/authoring/cross-references-divs.qmd b/docs/authoring/cross-references-divs.qmd index cd80888c5b..87ff7d6cc1 100644 --- a/docs/authoring/cross-references-divs.qmd +++ b/docs/authoring/cross-references-divs.qmd @@ -439,6 +439,6 @@ Scatterplot @fig-scatterplot ```` -Note that `.content-visible` and `.content-hidden` only control output visibility — the code cells inside still execute. To skip execution entirely based on the output format, have the cell read the `QUARTO_EXECUTE_INFO` environment variable. See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for details. +{{< include _visibility-vs-execution.md >}} When the variation you need is broader than output format — for example, the same document rendered as a draft vs. a final, or for an internal vs. an external audience — [project profiles](/docs/projects/profiles.qmd) can set alternate metadata per profile that `.content-visible when-meta=...` reads. This gives you another axis for conditional content beyond `when-format`. From f05ca191d83ea12f79202c3523bf6f382a5caaa5 Mon Sep 17 00:00:00 2001 From: christophe dervieux Date: Tue, 26 May 2026 17:12:34 +0200 Subject: [PATCH 10/10] Mention knitr format-detection helpers in r.qmd R cells run through knitr by default, which has long offered is_html_output(), is_latex_output(), and pandoc_to() for the common format-detection cases. Worth pointing readers at those alongside the engine-agnostic QUARTO_EXECUTE_INFO approach (flagged in the issue thread by cderv). Part of #13514. --- docs/computations/r.qmd | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/computations/r.qmd b/docs/computations/r.qmd index 260fa2adbd..6a5af8f2ac 100644 --- a/docs/computations/r.qmd +++ b/docs/computations/r.qmd @@ -173,6 +173,8 @@ if (is_html) { This pairs well with [conditional content](/docs/authoring/conditional.qmd) when both visibility and execution should depend on format. See [Execution Context Information](/docs/advanced/quarto-execute-info.qmd) for the full JSON schema. +For R cells using the knitr engine, knitr's `knitr::is_html_output()`, `knitr::is_latex_output()`, and `knitr::pandoc_to()` predicates are also available for the common format-detection cases. See the [knitr manual](https://pkg.yihui.org/knitr/manual#sec:man-output_type). + ## Output Formats {#output-formats} Another difference between R Markdown and Quarto is related to output formats. Quarto includes many more built in output formats (and many more options for customizing each format). Quarto also has native features for special project types like [Websites](/docs/websites/), [Books](/docs/books/), and [Blogs](/docs/websites/website-blog.qmd) (rather than relying on external packages).