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-executeEach 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).
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
```
````
`````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: trueA 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.
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.ymlis 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`.
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:
Nonerenders the textNone, 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.
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.
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.