Books with Jupyter¶

Jupyter Book is an open source project for building beautiful, publication-quality books and documents from computational material.

Here are some of the features of Jupyter Book:

Write publication-quality content in markdown
You can write in either Jupyter markdown, or an extended flavor of markdown with publishing features. This includes support for rich syntax such as citations and cross-references, math and equations, and figures.

Write content in Jupyter Notebooks
This allows you to include your code and outputs in your book. You can also write notebooks entirely in markdown to execute when you build your book.

Execute and cache your book’s content
For .ipynb and markdown notebooks, execute code and insert the latest outputs into your book. In addition, cache and re-use outputs to be used later.

Insert notebook outputs into your content
Generate outputs as you build your documentation, and insert them in-line with your content across pages.

Add interactivity to your book
You can toggle visibility of cells, connect with an online service like Binder, and include interactive outputs from Jupyter.

Generate a variety of outputs
This includes single- and multi-page websites, as well as PDF outputs.

Build books with a simple command-line interface
You can quickly generate your books with one command, like so: jupyter-book build mybook/

This website is built with Jupyter Book! You can browse its contents to the left to see what is possible.

Get involved with Jupyter Book!

Jupyter Book is an open community that welcomes your feedback, input, and contributions! Open an issue with any feedback. Give an issue a 👍 if you think it should be resolved and check out our enhancement voting leaderboard for the issues people want to see completed! If you’d like to contribute, check out our contributing guide.

Get started¶

To get started with Jupyter Book, you can either

check out the getting started guide,
browse the contents of the navigation menu of this book (to the left, if you’re on a laptop), or
review the example project shown immediately below (if you like learning from examples).

Warning

Jupyter Book 0.7 is a total re-write from 0.6, and some things have changed. See the legacy upgrade guide for how to upgrade, and legacy.jupyterbook.org for legacy documentation.

In addition, note that Jupyter Book is pre-1.0. Its API may change!

To install the jupyter-book pre-release from pip, run the following command:

pip install -U jupyter-book

A Small Example Project¶

Here’s a short example of a web-based book created by Jupyter Book.

Some of the features on display include

Jupyter notebook-style inputs and outputs
citations
numbered equations
numbered figures with captions and cross-referencing

The source files can be found on GitHub in the docs directory. These files are written in MyST markdown, an extension of Jupyter notebook markdown that allows for additional scientific markup. They could alternatively have been written directly as Jupyter notebooks.

Build the demo book

You can build this book locally on the command line via the following steps:

Ensure you have a recent version of Anaconda Python installed.
Clone the repository containing the demo book source files
```
git clone https://github.com/executablebooks/quantecon-mini-example
cd quantecon-mini-example
```
If you’d like to install Jupyter Book with pip, you can do so with:
```
pip install -U jupyter-book
```
See the getting started page for more information.
Install the Python libraries needed to run the code in this particular example from the environment.yml file. This includes the latest version of Jupyter Book:
```
conda env create -f environment.yml
conda activate qe-mini-example
```
Run Jupyter Book over the source files
```
jupyter-book build ./mini_book
```
View the result through a browser — try (with, say, firefox)
```
firefox mini_book/_build/html/index.html
```
(or simply double-click on the html file)

Now you might like to try editing the files in mini_book/docs and then rebuilding.

Further Reading

See the full QuantEcon example for a longer Jupyter Book use case, drawn from the same source material.

For more information on how to use Jupyter Book, see Overview and installation.

Under the hood - the components of Jupyter Book¶

Jupyter Book is a wrapper around a collection of tools in the Python ecosystem that make it easier to publish computational documents. Here are a few key pieces:

It uses the MyST markdown language in markdown and notebook documents. This allows users to write rich, publication-quality markup in their documents.
It uses the MyST-NB package to parse and read-in notebooks so they are built into your book.
It uses the Sphinx documentation engine to build outputs from your book’s content.
It uses a slightly modified version of the PyData Sphinx theme for beautiful HTML output.
It uses a collection of Sphinx plugins and tools to add new functionality.

For more information about the project behind many of these tools, see The Executable Book Project documentation.

Contribute to Jupyter Book¶

Jupyter Book is an open project and we welcome your feedback and contributions! To contribute to Jupyter Book, see Contribute to Jupyter Book.

Acknowledgements¶

Jupyter Book is supported by an open community of contributors, many of whom come from the Jupyter community. Jupyter Book and many of the tools it uses are stewarded by the Executable Book Project, which is supported in part by the Alfred P. Sloan foundation.