Sometimes you'd like to execute each page's content before building its HTML - this ensures that the outputs are up-to-date and that they still run. Jupyter Book has the ability to execute any code in your content when you build each page's HTML although by default this is disabled for notebook and simple markdown documents.
Jupyter Book will decide whether to execute your book's content based on the types of files used to store your content. By default, Jupyter Book assumes that :
- notebook outputs are already present in an
.ipynbfile, and consequently any Jupyter Notebooks (
.ipynbdocuments), will not be executed; (see below for how to change this behavior);
- simple raw markdown files (
.md, no Jupytext header) will also not be executed: Jupyter Book assumes that any code blocks were meant for viewing only, not running;
- any Jupytext documents (currently,
.Rmdfiles that have jupytext YAML front-matter content) will be executed when the page's HTML is built.
There are a few ways to alter this behavior in order to execute your book content at build time using several convenience functions and options which we'll cover below.
Jupyter Book provides a convenience command-line function that executes
one or more Jupyter Notebooks and stores the outputs inline within the same
ipynb file. This provides a straightforward way of ensuring that source notebook files contain freshly computed cell outputs when you create your Jupyter Book.
jupyter-book run command-line function can be called with the path to a single
book page like so:
jupyter-book run path/to/notebook.ipynb
It will simply execute the notebook and insert the code cell outputs in-place.
You can also specify a folder with a collection of pages as the first argument:
jupyter-book run path/to/notebook_folder
In this case, all notebooks in this folder and sub-folders will be run in-place.
If you'd like to run each page of your book (where possible) when building the
HTML for your book pages without modifying the original source document, use the
--execute flag when building each page's HTML:
jupyter-book build --execute
This will cause each
.ipynb and jupytext-formatted page to be executed when it is built.
In this case, the source content files will not be modified, but the code execution outputs will be placed in each page's HTML.
Remember that the HTML for each page is cached until you update your content. The
first time you run
jupyter-book build --execute, each page of your book will be run
and converted to HTML which may take some time. However, after the first run, only the pages that have been updated will be executed and converted to HTML, which should lead to subsequently faster build times as you update your content.
Here's a quick summary of this behavior:
|Jupyter Notebooks (
||Code executes; fresh outputs inserted inline in source notebook||Code doesn't execute; outstanding outputs displayed inline in HTML||Code executes; fresh outputs displayed inline in HTML|
|Raw markdown (
||Code doesn't execute||Code doesn't execute; generated code outputs not supported in raw markdown documents||Code doesn't execute; generated code outputs not available for HTML|
|Jupytext pages (
||Code outputs not supported in Jupytext documents||Code executes; fresh outputs displayed inline in HTML||Code executes; fresh outputs displayed inline in HTML|