Embedding Notebook Output

Overview

Quarto 1.3 supports embedding the output of external Jupyter notebooks within Quarto documents using the embed shortcode. To embed a notebook cell, provide the path to a Jupyter Notebook and cell identifier. For example, using this notebook:

You could embed the first code cell using the following shortcode:

{{< embed plots.ipynb#plot-dot >}}

Which will embed the plot as follows:

Source: plots.ipynb

Note that a link back to the source notebook is provided beneath the plot so that users can explore the notebook code used to produce the plot. See the section on Linked Source Notebooks for details on customizing or excluding these links.

Specifying Cells

The embed shortcode specifies target notebooks using an input relative path followed by a cell identifier (e.g. #plots.ipynb#plot-dot). If the cell identifier is omitted, all of the cells in the notebook will be embedded in the document.

The cell identifier in an embed is used to locate the proper cell using the following heuristics

  1. Cell id
    First, the cell metadata will be checked for a matching id , if found, this cell will be embedded. (Cell IDs are a newer feature of Jupyter Notebooks that are not yet well supported in Jupyter front ends, but this is checked for future compatibility as ids become more used).
  2. Label
    If no cell with an id is found, Quarto will use a cell that has a label in the code metadata which matches the embed’s id.
  3. Tags
    If no cell has been found, Quarto will use a cell or cell(s) which has a tag which matches the embed’s id.

Cell Tags

For example, to embed the output of a cell that you have given the tag plot-line within Jupyter Lab:

You would use the following embed:

{{< embed plots.ipynb#plot-line >}}

Which results in the following output:

Source: plots.ipynb

Embedding Code

In addition to embedding the output of a code cell, you may include the code from the cell by using the echo=true option. For example, the same embed with the echo option like:

{{< embed plots.ipynb#plot-dot echo=true >}}

This embeds both the code for the cell as well as the outputs of the code cell:

Source: plots.ipynb
Note

Code custom customization options for the document in which these cells are embedded will also control these code cells (for example, code-fold: true will fold the cells by default).

Code Cell Options

Content and code that is being embedded from Jupyter notebooks can also use code cell options like fig-cap, layout-ncol, to include additional options from the Notebook. For example, here we use several cell options in a notebook cell:

#| label: fig-fruit
#| fig-cap: Charts
#| fig-subcap: 
#|   - A distribution of the fruit that I eat each week
#|   - Another pie chart which shows a distribution of something
#| layout-ncol: 2

import matplotlib.pyplot as plt
x=[4,9,16,25,36]
fig = plt.figure(figsize =(5.5, 5.5))
plt.pie(x, labels=("Guavas", "Berries","Mangoes","Apples", "Avocado"),
colors = ( "#a86544", "#eb5b13", "#ebc713", "#bdeb13", "#8aeb13"))
plt.show()

x2=[4,9,16,25,36]
fig2 = plt.figure(figsize =(9, 5)) # line 4
plt.pie(x2)
plt.show()

When embedding this cell as follows:

{{< embed plots.ipynb#fig-fruit >}}

The following output is produced:

(a) A distribution of the fruit that I eat each week

(b) Another pie chart which shows a distribution of something

Figure 1: Charts

Source: plots.ipynb

Linked Source Notebooks

When you embed the contents of Notebooks in a Quarto document and render the document to HTML, Quarto will automatically include links to the source Notebooks that provided the embedded content. These links will by default appear both inline below the embedded content as well as below the TOC. For example, the following document embeds content from the notebook plots.ipynb. You can see the links in the rendered HTML document below:

Notebook Views

By default, Quarto will automatically generate an HTML rendering of the notebook which displays the contents of the notebook and includes a button to download the notebook. This makes it easier for users to view the Notebook contents without needing to download and run the Notebook locally. For example:

As an example, you can view the live preview for the `plots.ipynb` notebook used in this document.

View Options

You can control the behavior of notebook views using notebook-view. For each source notebook, you can provide a title and a url. The title will be used as the text of the any links to the source notebook and will also appear at the top of the rendered notebook view. The url, if provided, will be used as the href of any links to the source notebook. This is useful if you have deployed a copy of the source notebook to a site like Github, Google Colab, or Kaggle and would rather link to that instead.

For example:

notebook-view:
  - notebook: plots.ipynb
    title: "Plots and Computations"
    url: https://colab.research.google.com/drive/12GsIPQ644SI4vkEEHiZn-Qqfbr-bD1__

will result in links to the source notebook like so:

To disable the notebook views, and instead link directly to the Jupyter notebook (so the user may download the notebook with no intermediary view), set notebook-view to false.