Rendering

Introduction

This guide provides an overview of how to optimize your document rendering processes using Quarto. Whether you’re working with Jupyter notebooks or Quarto markdown files, this tutorial will enhance your productivity by teaching you:

  • Document Previewing: Quickly preview your work in various formats directly from the terminal.
  • Comprehensive Rendering: Understand the different rendering commands to generate HTML, PDF, or Docx outputs.
  • Parameterization: Customize documents dynamically by setting and using parameters in both Python and R environments.
  • Caching Strategies: Implement caching to expedite the rendering process and avoid redundant computations.
  • Execution Controls: Utilize Quarto’s flexible execution options to manage how and when your code runs.


Previewing

Previewing a document:

Terminal
# preview as html
quarto preview document.qmd

# preview as pdf
quarto preview document.qmd --to pdf

# preview a jupyter notebook
quarto preview document.ipynb

Rendering

Render documents into different formats using commands like:

Terminal
# all specified formats, default is html
quarto render document.qmd

# Render as pdf or docx
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

For Jupyter notebooks (.ipynb), use: quarto render document.ipynb

Note

Note: For .ipynb files, use --execute to run cells during rendering (if you did not already run them in the notebook).

Terminal
quarto render notebook.ipynb --execute

You can also specify this behavior within the notebook’s YAML front matter:

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

Parameterizing

Set parameters to create different variations of a document using Jupyter or Knitr:

  • In Jupyter, Quarto adopts Papermill’s syntax for parameters.
  • Tag a cell with parameters and set default values to parameterize a document.
```{python}
#| tags: [parameters]

alpha = 0.1
ratio = 0.1
```

The parameters are available in the top level environment:

```{python}
alpha
```

Use the params YAML option to define parameters:

---
params:
  alpha: 0.1
  ratio: 0.1
---

The parameters are available in the params list:

```{r}
params$alpha
```

Render with different parameters using -P for both .ipynb and .qmd:

quarto render document.ipynb -P alpha:0.2 -P ratio:0.3

Or use a YAML file for parameters and --execute-params:

quarto render document.qmd --execute-params params.yml

Caching

Cache code execution to speed up rendering and avoid re-executing unchanged code.

Settings

Setting depends on the execution engine you are using (Jupyter or Knitr).

Install Jupyter Cache:

  • Mac/Linux python3 -m pip install jupyter-cache
  • Windows py -m pip install jupyter-cache

Enable caching globally in YAML:

---
title: "My Document"
format: html
execute: 
  cache: true
---

Or at the project level:

project:
  type: website
  
format:
  html:
    theme: united
    
execute:
  cache: true
Note

If desired, you can use the jcache command line to manage notebook caches. See Jupyter Cache documentation.

Enable caching globally in YAML:

---
title: "My Document"
format: html
execute: 
  cache: true
---

Or individually per cell:

```{r}
#| cache: true

summary(cars)
```

Read more:

Rendering

You can use quarto render command line options to control caching behavior without changing the document’s code.

Control quarto render caching with command line options:

  • --cache: Force caching for all chunks (even if not enabled in options).
  • --no-cache: Disable caching for all chunks (even if enabled in options).
  • --cache-refresh: Refresh cache for all chunks (even if it has not been invalidated).

Alternatives

Disabling Execution

For prose/markdown work, disable code execution with:

execute: 
  enabled: false

In Jupyter .ipynb notebooks, code doesn’t execute with quarto render by default.

Freezing Execution

The freeze option prevents documents from re-rendering during a full project render or allows re-rendering only when their source changes.

# Never re-render during project render
execute:
  freeze: true  
# Re-render only when source changes
execute:
  freeze: auto

Freeze affects execution during full project renders. For individual documents or sub-directory renders, code execution is always performed.

Terminal
# Render single document (always executes code)
quarto render document.qmd

# Render project subdirectory (always executes code)
quarto render articles

References