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 Notebook
This allows you to include your code and outputs in your book. You can also write notebooks entirely in Markdown that get executed when you build your book.
- Execute and cache your book’s content
.ipynband 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
- 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!
Install Jupyter Book¶
You can install Jupyter Book via
pip install -U jupyter-book
This will install everything you need to build a Jupyter Book locally.
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).
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
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 the 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
Install the Python libraries needed to run the code in this particular example from the
environment.ymlfile. 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)
(or simply double-click on the
Now you might like to try editing the files in
mini_book/docs and then
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.