Executing pages of your book
✨experimental✨
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.
Default execution behavior
By default, Jupyter Book will decide whether to execute your book's content based on
the types of files used to store your content. By default, any Jupyter Notebooks will
not be executed, Jupyter Book assumes that the notebook outputs are already
present in the ipynb
file (see below for how to change this behavior). In addition,
raw markdown files will also not be executed, as Jupyter Book assumes that any
code blocks were meant for viewing only, not running. However, any
Jupytext documents content will be executed when the page's HTML is built.
This can be either .py
, .md
, or .Rmd
files that have jupytext YAML front-matter.
There are a few ways to alter this behavior, which we'll cover below:
It's possible to execute your book content at build time. There are a few convenience functions and options for this:
Run all your book's content when building: jupyter-book build --execute
If you'd like to run each page of your book (where possible) when building the
HTML for your book pages, you may use the --execute
flag when you build each page's HTML. 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 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. However, after this, only the pages that have been updated will
be executed and converted to HTML, so while this will take a long
time the first time you run it (since all your book content will need to run), it
should be incrementally faster in subsequent builds.
Here's a quick summary of this behavior:
Type | Default | --execute |
---|---|---|
Jupyter Notebooks (.ipynb ) |
Doesn't execute | Executes |
Raw markdown (.md ) |
Doesn't execute | Executes |
Jupytext pages (.md , .Rmd , .py ) |
Executes | Executes |
Run a single page in-place: jupyter-book run
Jupyter Book also provides a convenience command-line function that executes a
single Jupyter Notebook and stores the outputs in the same ipynb
file.
This is a command-line function that allows you to quickly execute pages of your book and store the content in-line. You can use it with a path to a single book page like so:
jupyter-book run path/to/notebook.ipynb
And it will simply run the execute 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.