Books with Jupyter

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

Jupyter Book has the following main features:

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

Warning

Jupyter Book 0.7 is a total re-write from 0.6, and some things have changed. Open an issue with any feedback! 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!

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).

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

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:

  1. Ensure you have a recent version of Anaconda Python installed.

  2. Clone the repository containing the demo book source files

    git clone https://github.com/executablebooks/quantecon-mini-example
    cd quantecon-mini-example
    
  3. 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
    
  4. Run Jupyter Book over the source files

    jupyter-book build ./mini_book
    
  5. 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.