Skip to main content

Jupyter Notebooks

Jupyter Notebooks are a popular format for data science and reproducible research. This article provides a guide to how to write, and collaborate on, a reproducible research article using Jupyter Notebooks and Stencila.


There are many resources available for how to use Jupyter Notebooks for reproducible research including:

If you are getting started with Jupyter Notebook please consult these and other resources. In the rest of this document, we are only going to cover the slightly more advanced topics of how to turn your notebook into a properly structured executable research article suitable for publication.

Markdown cells#

Most Jupyter notebooks have two types of cells: Markdown cells and code cells. Markdown cells are for static content that is not generated from code (e.g. narrative prose, tables, static images). There are a few extensions to Markdown that you can use make you document more structured and suitable for publication.

Adding figure and table captions#

Markdown does not have good support for table or figure labels and captions. Often authors will just merge the label and the caption togther in a bolded paragraph. For more structured captions, having a title and paragraph as is often found in academic journals, we suggest that you use a figure or table block to wrap your image or Markdown table. e.g.

figure: Figure 1
### The title for my figure
A paragraph for my figure including some **strong** emphasis.

These will be converted by Stencila to the correct structures for publication in other formats such as JATS XML and HTML.

Code cells#

As with static figures and tables, Stencila also supports more structured labels and captions for dynamic figures and tables generated by code.

To add a label and/or caption to a code cell in a Jupyter Notebook you need to add it to the cell's metadata. To do that, within the notebook interface's menu select View > Cell Toolbar > Edit Metadata:

This should result in the Edit Metadata button showing in the top-right corner of each code cell:

You can then add id (so that you can link to the figure from elsewhere in the document), label and caption properties of the code cell. The caption property can be Markdown in which case, Stencila will parse into a structured caption. For example, Figure 2 of this executable article:

Last updated on by Nokome Bentley