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:
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
- Cell
id
First, the cell metadata will be checked for a matchingid
, 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). - Label
If no cell with anid
is found, Quarto will use a cell that has alabel
in the code metadata which matches the embed’s id. - 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.
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:
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
=[4,9,16,25,36]
x= plt.figure(figsize =(5.5, 5.5))
fig =("Guavas", "Berries","Mangoes","Apples", "Avocado"),
plt.pie(x, labels= ( "#a86544", "#eb5b13", "#ebc713", "#bdeb13", "#8aeb13"))
colors
plt.show()
=[4,9,16,25,36]
x2= plt.figure(figsize =(9, 5)) # line 4
fig2
plt.pie(x2) plt.show()
When embedding this cell as follows:
{{< embed plots.ipynb#fig-fruit >}}
The following output is produced:
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:
Link Placement
You can control the placement of the links to source notebook by specifying the option notebook-links
with one of the following values:
false
-
Do not display any links to source notebooks.
inline
-
Display only the inline links to source notebooks (which appear below the embedded content). Do not display links to the source document alongside the TOC.
global
-
Display only links to source notebooks alongside the TOC. Do not display links inline below the embedded content.
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
.