Embedding Jupyter Notebook Cells

Quarto 1.3 Feature

This feature is new in Quarto 1.3, which you can download at https://quarto.org/docs/download/

Overview

You can include the output of an external Jupyter notebook in a Quarto document with the embed shortcode. To embed a notebook cell, provide the path to a Jupyter Notebook and a cell identifier. For example, this notebook called penguins.ipynb has a cell labelled fig-bill-scatter:

A screenshot of a Jupyter Notebook with the name 'penguins.ipynb', with a cell highlighted that has the code chunk option label set to fig-bill-scatter. Below the cell is the resulting plot.

You can use the following shortcode to embed the output of this cell:

{{< embed penguins.ipynb#fig-bill-scatter >}}

This will embed the plot as follows:

Figure 1: A scatterplot of bill dimensions for penguins, made with Altair.
Source: Palmer Penguins

A link to the source notebook is automatically provided beneath the plot. Following the link takes users to a rendered version of the notebook, allowing them to explore the notebook without having to download and run it locally. For example, clicking on the link to penguins.ipynb gets you to a page that looks like the following:

A screenshot of webpage with the title 'penguins.ipynb', a large blue button labelled 'Download Notebook', followed by the notebook contents.

Beyond this basic usage, you can also:

  • Specify cells in multiple ways, see Specifying Cells.

  • Control the output using code cell options in the source Notebook, including things like figure captions, figure layout, and code display, see Code Cell Options.

  • Include the cell code along with the output by adding an echo option to the shortcode, see Embedding Code.

  • Customize or exclude the link to the the source notebooks, see Links to Source Notebooks.

Specifying Cells

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

The cell identifier 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. (Cell IDs are a newer feature of Jupyter Notebooks that are not yet well supported in Jupyter front ends, but id is checked first to allow for future compatibility as they become more common).
  2. Label
    If no cell with a matching id is found, Quarto will use a cell that has a label in the code metadata which matches the cell identifier.
  3. Tags
    If no cell has been found, Quarto will use a cell or cell(s) whose tag matches the cell identifier.

Cell Tags

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

Screenshot of a code cell in a Jupyter Notebook with the cell tags open in the cell toolbar and displaying the tag 'bill-ratio'.

You would use the following embed:

{{< embed penguins.ipynb#bill-ratio >}}

Which results in the following output:

A density plot of bill ratio by species.

Code Cell Options

Code cell options from the source Jupyter Notebook are propagated to the document in which they are embedded. For instance, you may specify code cell options like fig-cap, fig-alt and layout-ncol, to control aspects of embedded figures. For example, this cell in the Notebook specifies figure options including a caption, sub-caption, alt text and layout:

penguins.ipynb
#| label: fig-bill-marginal
#| fig-cap: "Marginal distributions of bill dimensions"
#| fig-subcap: 
#|   - "Gentoo penguins tend to have thinner bills,"
#|   - "and Adelie penguins tend to have shorter bills."
#| fig-alt:
#|   - "Density plot of bill depth by species."
#|   - "Density plot of bill length by species."
#| layout-ncol: 2

sns.displot(penguins, 
            x = "bill_depth_mm", 
            hue = "species", 
            kind = "kde", fill = True, aspect = 2, height = 3)
plt.show()
sns.displot(penguins, 
            x = "bill_length_mm", 
            hue = "species", 
            kind = "kde", fill = True, aspect = 2, height = 3)
plt.show()

When this cell is embedded:

{{< embed penguins.ipynb#fig-bill-marginal >}}

The following output is produced:

Density plot of bill depth by species.

(a) Gentoo penguins tend to have thinner bills,

Density plot of bill length by species.

(b) and Adelie penguins tend to have shorter bills.

Figure 2: Marginal distributions of bill dimensions

Embedding Code

You may include the code from a cell along with the output by using the echo=true option. For example, to include the code and the plot from the cell labelled species-counts the embed would be:

{{< embed penguins.ipynb#species-counts echo=true >}}

The result in the document is both the code and output for the cell:

penguins.groupby("species").size().reset_index(name = "count")
species count
0 Adelie 152
1 Chinstrap 68
2 Gentoo 124

Like figure options, options for displaying the code will propagate from the source Jupyter Notebook. For example, to fold the code for this cell, you could add code-fold: true to the options for the species-counts cell:

penguins.ipynb
#| label: species-counts
#| code-fold: true
penguins.groupby("species").size().reset_index(name = "count")

The options set in the YAML header for the document in which these cells are embedded will also control these code cells. For example, to fold all the code, including the code embedded from penguins.ipynb, you could add code-fold: true to the document YAML:

sample.qmd
title: Exploration of penguin characteristics
author: Norah Jones
toc: true
format:
  html:
    code-fold: true

Links to 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 table of contents. For example, the following document embeds content from the notebook penguins.ipynb. You can see the links in the rendered HTML document below:

Screenshot of a rendered page with an embedded plot. A link to the Source 'penguins.ipynb' is shown directly below the plot. A similar link is shown below the table of contents under the heading 'Notebooks'.

Notebook Views

By default, the link to the source notebook goes to an automatically generated HTML render of the notebook. This makes it easier for users to view the Notebook contents without needing to download and run the Notebook locally. This notebook view displays the contents of the notebook and includes a button to download the notebook. For example:

A screenshot of webpage with the title 'penguins.ipynb', a large blue button labelled 'Download Notebook', followed by the notebook contents.

As an example, you can view the live preview for the `penguins.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: penguins.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:

Screenshot of a rendered page with an embedded plot. A link to the Source 'Plots and Computations' is shown directly below the plot. A similar link is shown below the table of contents under the heading 'Notebooks'.

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.