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 33b11cafb4..3ba08f8305 100644 --- a/docs/authoring/conditional.qmd +++ b/docs/authoring/conditional.qmd @@ -112,4 +112,8 @@ 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 + +{{< include _visibility-vs-execution.md >}} diff --git a/docs/authoring/cross-references-divs.qmd b/docs/authoring/cross-references-divs.qmd index 59dc99ab15..87ff7d6cc1 100644 --- a/docs/authoring/cross-references-divs.qmd +++ b/docs/authoring/cross-references-divs.qmd @@ -438,3 +438,7 @@ Scatterplot @fig-scatterplot ```` + +{{< 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`. 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. 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} 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. diff --git a/docs/computations/r.qmd b/docs/computations/r.qmd index 4559b946e9..6a5af8f2ac 100644 --- a/docs/computations/r.qmd +++ b/docs/computations/r.qmd @@ -156,6 +156,25 @@ 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. + +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).