Inline Execution for Jupyter

Pre-release Feature

This feature is new in the upcoming Quarto 1.4 release. To use the feature now, you’ll need to download and install the Quarto pre-release.

Overview

Quarto v1.4 includes support for executing inline expressions when using Jupyter kernels. Inline expressions are similar to code blocks, except that they use a single tick (`) rather than triple tick (```) and can appear anywhere. For example, the following code:

```{python}
x = 5
```

The answer is `{python} x`

Will create this markdown output:

The answer is 5.

This syntax works for any Jupyter kernel—so for Julia you would write an inline expression as `{julia} x`).

Usage in Notebooks

Inline expressions are always evaulated when rendering and previewing .qmd files. However, for notebooks you need to execute the notebook with Quarto in order to evaluate inline expressions (i.e. they won’t be evaluated within the JupyterLab, VS Code, or PyCharm notebook editor).

You can work in your favorite notebook front-end without Quarto execution, then once you are ready to publish execute the notebook during rendering as follows:

Terminal

$ quarto render notebook.ipynb --execute

You can also turn on execution within the YAML options of a notebook. For example:

---
title: "My Notebooks"
execute:
  enabled: true
---

Markdown Output

Note that by default, the output of inline expressions is treated as ordinary text (i.e. markdown within it is not rendered). Any markdown like syntax within the output of inline expressions will be automatically escaped. For example, the following inline expression:

`{python} '**not bold**'`

Will produce the following markdown:

\*\*not bold\*\*

If you want to explicitly create markdown output, use the Markdown() function from IPython.display. For example, the following inline expression will result in bolded text:

```{python}
from IPython.display import Markdown
```

`{python} Markdown('**bold**')`

Note that for the Knitr engine, you use the I() function to designate that inline output has markdown to render. For example:

`{r} I('**bold**')`

Escaping

If you are writing documentation about inline expressions (as we are in this article!) then you may need to escape the syntax so that it doesn’t execute. You can do that in one of two ways:

1. Use a double-brace around the expression. For example: `{{python}} x`

2. Enclose the expression in an extra backtick. For example: ``{python} x``

Each of the expressions above will render (unexpected) as `{python} x` within the output document.

Engine Binding

If you use inline expressions in a document that does not have any other executable code blocks then you should explicitly set the engine document option to ensure that your expressions are evaluated (automatic engine binding works for blocks but not inlines). For example:

---
title: "My Document"
engine: jupyter
---

`{python} "hello"`

Syntax Compatibility

The Knitr and Observable engines each have their own syntax for inline expressions. To make it easier to learn and use expressions across engines, there is also a mapping from the Jupyter-compatible syntax to the native synaxes of Knitr and Observable. For example:

Engine	Example	Converted
Knitr	`{r} x`	`r x`
Observable	`{ojs} x`	${x}

So you can use either the standard Quarto inline expression syntax or the native syntax with these engines.

Note that native Knitr inline syntax has a different default behavior for handling of markdown content. Specificially, it treats all inline output as containing markdown (whereas Quarto assumes that it doesn’t). So a strict equivalency between the Knitr and Quarto syntax would be:

Knitr	Quarto
`r "**bold**"`	`{r} I("**bold**")`