Skip to main content

Computations

Overview

A Quarto document can contain executable cells: fenced code blocks whose info string is a language name wrapped in braces. Quarto hands each cell to an engine, runs it, and splices the results into the rendered document. For example, a cell written like this:

```{r}
sum(1:10)
```

would, if run, produce 55 underneath it in the rendered page. (This page only shows cells like this one — see the next section — so nothing on it actually runs.)

Rendering without running any code

q2 render --no-execute renders a document, or a whole project, without executing any cell:

q2 render report.qmd --no-execute

Each cell is shown as code with no output, and no engine is started, so this works on a machine without R, Python or Julia installed. Use it to check a layout quickly, or to render a document whose cells are slow or currently failing. A Jupyter notebook (.ipynb) still shows the outputs stored in it; see Notebooks.

--execute is the default, and it means “execute as the documents ask”. It exists to cancel an earlier --no-execute on the same command line (the last of the two wins).

NoteMigrating from Quarto 1

In Quarto 1, --execute forces execution, overriding a document’s execute: enabled: false. In Quarto 2 it does not: a document that turns execution off stays off. To execute such a document anyway, override its metadata for the one render, with -M 'execute:{enabled: true}'.

Displaying code cells without running them

Writing about Quarto means showing readers what a cell looks like without running it — for example, in a tutorial or in this documentation. The rule is the ordinary Markdown one: a fenced code block is displayed verbatim, so a cell written inside one is shown, not executed.

To display the cell above instead of running it, wrap it in a fence with more backticks than the cell uses:

````markdown
```{r}
sum(1:10)
```
````

which renders as:

```{r}
sum(1:10)
```

The braces stay single. Nothing about the inner cell changes — it is shown exactly as an author would type it, which is the point: a reader can copy it straight into their own document.

The outer fence must be longer

Markdown decides where a fenced code block ends by matching the length of its opening fence. So the wrapping fence only needs to be longer than the longest run of backticks inside it — one backtick longer is enough. A cell written with the ordinary three backticks is displayed by wrapping it in four; if the content being displayed already contains a four-backtick fence, wrap that in five, and so on.

Cell options are displayed too

Options on the fence header, and Quarto’s #| comment options, are part of the cell and are displayed along with it — nothing needs to be stripped or adjusted. A fence-header option:

```{r, echo=FALSE}
plot(1:10)
```

and a #| comment option:

```{r}
#| echo: false
#| label: fig-example
plot(1:10)
```

Displaying a block that itself displays a cell

The same rule applies at any depth: each layer’s fence just needs to be longer than the longest fence nested inside it. To show a document like this page — one that itself displays a cell — add one more layer of backticks:

`````markdown
````markdown
```{python}
1 + 1
```
````
`````
NoteMigrating from Quarto 1

Quarto 1 used doubled curly braces for this — a cell written as {{python}} was displayed, with single braces, instead of running. Quarto 2 does not support this escape: doubled braces in a fence header produce a warning (Q-2-50), and the fix is the markdown code block shown above. Dropping the escape also means code blocks that genuinely contain doubled braces — Jinja or Mustache templates, GitHub Actions expressions — render correctly, where Quarto 1 would collapse them.

Cell openers

A code cell starts with a fence whose header is a single language token in braces:

```{python}
1 + 1
```

The token is letters, digits, _, . and -, starts with a letter, and is matched case-insensitively. A dot is part of the token: {python.marimo} is one token, naming a language and the engine flavor together. A space starts a class instead: {python .marimo} is a python cell with the class marimo.

Options never go inside the braces. Put them in #| lines at the top of the cell:

```{python}
#| echo: false
1 + 1
```

A header such as {python echo=false} is the knitr style and is rejected with error Q-2-36.

Where a cell’s output appears

By default, a cell shows its code first and all of its output after the code, even when the cell prints between statements:

```{julia}
println("first")
x = 1
println("second")
x + 1
```

The rendered cell has one code block, followed by the outputs first, second, and 2.

The output-interleave option changes that. Set it to true and the cell alternates code and output in the order the statements ran: the code up to the first println, its output, the next statement, and so on. Set it in a cell:

```{julia}
#| output-interleave: true
println("first")
x = 1
println("second")
x + 1
```

or for the whole document, under execute:

execute:
  output-interleave: true

A cell’s own setting overrides the document’s setting.

Engines differ in whether they interleave by default:

Engine Default output-interleave
Knitr Interleaves false holds the output
Julia Holds true interleaves
Jupyter Holds No effect yet

For knitr cells that interleave, the chunk options results: hold and fig.show: hold still work. They hold only printed text or only plots, and leave messages and warnings where they were produced. output-interleave: false holds everything.

NoteMigrating from Quarto 1

Quarto 1 interleaved knitr output and held Julia and Jupyter output. Quarto 2 keeps those defaults. The new option lets Julia cells interleave. It also lets knitr cells hold all of their output, without choosing between results: hold and fig.show: hold.

Inline expressions

A document can also compute a value inline — inside a sentence, or inside an attribute — so that the result appears in place of the expression. Quarto has two spellings for this, and they differ in how the computed value is inserted.

The brace spelling mirrors the cell syntax and works across engines:

The current release is `{r} release_version`.

The classic spelling is knitr’s own, inherited from R Markdown, and predates Quarto. It is available with the knitr engine only:

The current release is `r release_version`.

The two spellings insert the value differently

The brace spelling escapes Markdown’s special characters in the value: whatever the expression returns is shown as text, exactly as it came out. The classic spelling inserts the value as Markdown, so formatting carried in the value is interpreted.

With notice set to **important**:

Written Renders as
`{r} notice` **important**
`r notice` important

To opt the brace spelling into Markdown, wrap the value in knitr’s I():

The notice is `{r} I(notice)`.

That makes the two spellings equivalent: `r x` does the same thing as `{r} I(x)`.

Reach for the brace spelling when the value comes from somewhere you do not control. Markdown admits inline HTML, so a value inserted as Markdown can bring markup with it; the brace spelling’s escaping is the default for exactly that reason.

Where inline expressions work

Inline expressions are evaluated in three places: prose, attribute values (a fenced div’s attributes, or a link title), and the document’s own front matter:

The current release is `{r} release_version`.

::: {#hero data-version="`{r} release_version`"}
Download the latest build.
:::

[Download](https://example.com/dl "Version `{r} release_version`")

In front matter, write the expression inside a quoted string:

---
title: "Report for `{python} __import__('datetime').date.today().year`"
jupyter: python3
---

Front matter is evaluated before any cell runs, so a span there cannot use variables a cell defines. A value that would put a newline inside a YAML string stops the render and names the key.

They are left exactly as written in these places:

  • any fenced code block, whether braced (a {r} cell) or not, and whatever its language;
  • HTML comments;
  • project-level metadata: _quarto.yml, _metadata.yml, and extension or format defaults. A span in _quarto.yml is not evaluated, even though one in a document’s own front matter is;
  • a span written in a language no engine in the document owns, such as `{zzz} x`.
NoteMigrating from Quarto 1

Quarto 1 also evaluated a span written inside a braced {r} cell (a comment such as {python} # a xspan). Quarto 2 treats the cell body as code and leaves it alone.

Inline expressions with Jupyter

With the Jupyter engine, a `{python} expr` span runs in the document’s kernel, so it sees the state left by earlier cells. The language token matches case-insensitively: {Python} also runs in Quarto 2, though Quarto 1 does not recognize it.

```{python}
total = 40 + 2
```

The answer is `{python} total`.

The span is an expression, as in Quarto 1. A statement such as y = 5 has no value; the kernel answers with a SyntaxError and the render stops with error Q-18-10, naming the span as file:line:col together with the kernel’s message. error: true does not apply to a span, and neither does execute: eval: false: a span runs either way.

How a value is inserted

As with knitr’s brace spelling, the value is inserted as text, with Markdown’s special characters escaped. To insert Markdown (or HTML) instead, return it from IPython.display:

```{python}
from IPython.display import Markdown
note = Markdown("**important**")
```

The notice is `{python} note`.

Markdown(...) is the Jupyter analog of knitr’s I().

Two values need a word:

  • None renders the text None, because that is the value’s text.
  • An empty string, or any value with no text form Quarto can place in the page (for example only a plot), leaves the span’s source in the document. The second case also prints a warning naming the file and line; the render still succeeds.
WarningEmpty values differ by engine

An empty string leaves the span source in place with Jupyter, while knitr and Julia render nothing. This is not settled, so do not rely on either behavior across engines.

Documents that contain only inline expressions

A document with no executable cell has no code for Quarto to hand to an engine, so it needs a hint. Without one, its spans are left as written and no kernel starts. Select the engine in the document’s own front matter:

---
title: Spans only
jupyter: python3
---

Today is `{python} __import__("datetime").date.today().year`.

engine: jupyter works too. The key must be in the document’s own front matter: engine: in _quarto.yml does not make a page without cells run its spans, as in Quarto 1. A page with at least one executable cell needs no key.

To show a span as code instead of running it, wrap it in a markdown code block, as in Writing about an inline expression. Doubling the braces is not an escape: `{{python}} x` is left alone, but it is displayed with both pairs of braces.

Other engines

  • knitr: unchanged. Both spellings work as described above.

  • Julia: spans use the brace spelling, and Julia evaluates them. It finds spans by parsing the document as Markdown rather than scanning its text, so a couple of cases come out differently from Jupyter:

    • A span in the document’s own front matter is left as written. Julia does not evaluate front matter spans.
    • The language and the code must be separated by one space. A tab leaves the span as written.

    As in any document, a span in a language that no engine in the document owns is left as written.

  • marimo: inline expressions are not supported. marimo runs no spans, so a `{python} x` span in a marimo document is left as written, with no output. Compute the value in a cell and show it there.

Writing about an inline expression

The rule is the one from Displaying code cells without running them, and nothing about it changes for inline expressions: write it inside a markdown block and it is displayed rather than run.

```markdown
The current release is `{r} release_version`.
```

which renders as:

The current release is `{r} release_version`.

The expression is shown exactly as an author would type it, together with the prose around it, so a reader can copy the whole line into their own document. As with cells, the wrapping fence only needs to be longer than the longest run of backticks inside it.

Any fenced code block displays its text and never evaluates it, so the same holds for a block with no language, or one labelled with another language such as ```r or ```text. A braced {r} cell is code, not prose, and is not scanned for spans at all. Reach for markdown when what you are showing is Quarto syntax, because that is the label that tells readers (and highlighters) what the block contains.

NoteMigrating from Quarto 1

Quarto 1 had a doubled-brace escape for inline expressions too: `{{r}} x` was displayed as `{r} x`. Quarto 2 drops it for the same reason it drops the doubled-brace escape for cells — the markdown code block above does the job, and leaving doubled braces alone is what lets Jinja and Mustache templates render correctly.