Skip to content

The Jupyter Book Wiki

Jump to bottom
Chris Holdgraf edited this page Sep 3, 2020 · 2 revisions

This is a wiki for information about the Jupyter Book project.

The Jupyter Book legacy upgrade guide

With the release of Jupyter Book v0.7.0, there are several new ways to configure, structure, and build your book. The following sections describe some of the major considerations, and how to upgrade your book:

Terminology

  • legacy jupyter book: The original version of Jupyter Book (currently at jupyterbook.org, eventually legacy.jupyterbook.org)
  • new jupyter book: The new version of Jupyter Book (currently at beta.jupyterbook.org)

Major changes

Your book's structure

Because the new Jupyter Book uses only Python to build your book, you don't need the full structure of a Jekyll website in your book's repository (e.g. the _include, assets/ etc folders). Instead, you only need 3 things in book's repository:

  • Your book content (e.g. myfile.md, intro.ipynb)
  • Your Table of Contents file (_toc.yml)
  • (optional) your book's configuration file (_config.yml)

That's all you need to build your book.

For example, here is the old structure of a jupyter book:

├── assets
│   └── custom
│       ├── custom.css
│       └── custom.js
├── _includes
│   └── ...
├── _templates
│   └── ...
├── content
│   └── features
│      ├── features.md
│      └── notebooks.ipynb
├── _config.yml
└── _data
    └── toc.yml

and here is the new structure for the same book:

├── features
│   ├── features.md
│   └── notebooks.ipynb
├── _config.yml
└── _toc.yml

Configuration and

The structure of your book's _config.yml file is slightly different in order to be more streamlined and less-complex. Most of the same options for configurability are still there, but the key:val pairs might be a bit different. See the new jupyter book configuration page for a reference of all of the values you can control.

Table of Contents structure

The structure of your book's _toc.yml file is also slightly different. In particular, the url: key is now called file:. See the new table of contents documentation for more information on this file. url: is now reserved for adding external links to your TOC.

Here's what an old jupyter book TOC looks like:

- url: /features/features
  not_numbered: true
  expand_sections: true
  sections:
  - url: /features/markdown
    not_numbered: true
  - url: /features/notebooks
    not_numbered: true

- header: Here's a header
- url: /features/features2

And here is the new book version of the same TOC:

- file: features/features
  expand_sections: true
  sections:
  - file: features/markdown
  - file: features/notebooks

- header: Here's a header
- file: features/features2

The installation and build process

Because the underlying build system is different, the new process for building a book is simpler and requires fewer steps to install and build.

The old version of jupyter book required you to pip install jupyter book, then run a command to install Ruby and Jekyll locally. Building books required first building each page's HTML with Python, and then building the book with Jekyll (or using a docker image to run these commands).

The new version of Jupyter Book uses Sphinx the whole way through. This means that installing Jupyter Book is just running pip install jupyter-book, and building a book is just running jupyter-book build mybook/. That's it!

Previewing your built book

The old version of Jupyter Book required you to use Jekyll to serve your book, which you would call with make serve after building your book.

The new version of Jupyter Book uses Sphinx to build a standalone collection of HTML files that do not need a server to preview. After you build your book, the html files will be placed in _build/html. You can preview your book by clicking on one of the HTML files in this folder (e.g., _build/html/index.html).

The supported markup languages

The other major change is in the supported markup language(s) for your book. These are:

  • CommonMark markdown (aka, Jupyter markdown)
  • MyST markdown (an extended CommonMark markdown)

You can still write your book content in CommonMark markdown (either in Jupyter Notebooks or in markdown files). However, you can now also write MyST markdown. This is an extension of CommonMark markdown that allows you to call roles and directives, which are kind of like custom functions in markdown. You can use this to control different parts of your book, change the layout of some content, etc.

Notebook cell tags

The old version of Jupyter Book used cell tags to control the behavior of elements on the page. The new version of Jupyter Book uses tags as well, but has slightly different expectations for markdown vs. code cells. In short:

The new Jupyter Book expects you to use directives for markdown cells, and tags for code cells.

For example, see the documentation about margins. To add a margin within a markdown cell, use a directive like so:

```{margin}
Here's my margin content
```

To convert a code cell to be a margin, add the margin tag to it.

Under the hood changes

The biggest technical change is that the new Jupyter Book uses the Sphinx documentation engine in order to build books. This is a fully-fledged documentation tool that allows for a number of publication-quality features such as references, citations, and numbered equations.

The old version of Jupyter Book used Jekyll, a static site generator, to build books. This worked well for simple books, but it was difficult for users to install, and also didn't support "documentation" or "publication" features.

See https://jupyterbook.org/advanced/contributing.html#repository-structure-of-jupyter-book for more information

Clone this wiki locally