Contents

Overview

This is a short overview of the major components and steps in building a Jupyter Book. See the other pages in this guide for more in-depth information.

Install Jupyter Book

You can install Jupyter Book via pip:

pip install -U jupyter-book

This will install everything you need to build a Jupyter Book locally.

The Jupyter Book command-line interface

Jupyter Book uses a command-line interface to perform a variety of actions. For example, building and cleaning books. You can run the following command to see what options are at your control:

You can also use the short-hand jb for jupyter-book. E.g.,: jb create mybookname. We’ll use jupyter-book for the rest of this guide.

jupyter-book --help

Usage: jupyter-book [OPTIONS] COMMAND [ARGS]...

  Build and manage books with Jupyter.

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  build   Convert your book's or page's content to HTML or a PDF.
  clean   Empty the _build directory except jupyter_cache.
  config  Inspect your _config.yml file.
  create  Create a Jupyter Book template that you can customize.
  myst    Manipulate MyST markdown files.
  toc     Command-line for sphinx-external-toc.

For more complete information about the CLI, see Command-line interface reference.

The book building process

Building a Jupyter Book broadly consists of these steps:

  1. Create your book’s content. You structure your book with a collection of folders, files, and configuration. See Anatomy of a Jupyter Book.

  2. Build your book. Using Jupyter Book’s command-line interface you can convert your pages into either an HTML or a PDF book. See Build your book.

  3. Publish your book online. Once your book is built, you can share it with others. Most common is to build HTML, and host it as a public website. See Publish your book online.

注解

We will use the word “book” to describe the outputs generated by this tutorial, but you can also use Jupyter Book to build articles. See Structure of an Article for more information.

Anatomy of a Jupyter Book

There are three things that you need in order to build a Jupyter Book:

  • A configuration file (_config.yml)

  • A table of contents file (_toc.yml)

  • Your book’s content

For example, consider the following folder structure, which makes up a simple Jupyter Book.

mybookname/
├── _config.yml
├── _toc.yml
├── landing-page.md
└── page1.ipynb

We’ll cover each briefly below, and you can find more information about them elsewhere in this documentation.

Book configuration (_config.yml)

All of the configuration for your book is in a YAML file called _config.yml.

You can define metadata for your book (such as its title), add a book logo, turn on different “interactive” buttons (such as a Binder button for pages built from a Jupyter Notebook), and more.

For more information about your book’s configuration file, see Configuration reference.

Here’s an example of a simple _config.yml file:

# in _config.yml
title: "My book title"
logo: images/logo-wide.svg
execute:
  execute_notebooks: "off"

  • title: defines a title for the book. It will show up in the left sidebar.

  • logo: defines a path to an image file for your book’s logo (it will also show up in the sidebar).

  • execute: contains a collection of configuration options to control execution and cacheing.

    • execute_notebooks: "off" tells Jupyter Book not to execute any computational content that it finds when building the book. By default, Jupyter Book executes and caches all book content.

More about _config.yml

There is much more that you can do with the _config.yml file. For example, you can Add source repository buttons or add Interactive data visualizations. For a complete list of fields for _config.yml, see Configuration reference.

Table of Contents (_toc.yml)

Jupyter Book uses your Table of Contents to define the structure of your book. For example, your chapters, sub-chapters, etc.

This is a YAML file with a collection of pages, each one linking to a file in your book. Here’s an example of the two content files shown above.

If you would like to quickly generate a basic Table of Contents YAML file, run the following command:

jupyter-book toc mybookname/

And it will generate a TOC for you. Note that there must be at least one content file in each folder in order for any sub-folders to be parsed.

# In _toc.yml
format: jb-book
root: landing-page
chapters:
- file: page1

The _toc.yml is arranged with a format such as jb-article, or jb-book. The root item is considered the landing page (for html builds) and is used as front matter (for latex builds). For jb-book, subsequent chapters can be added under the chapters: section in the yml file.

Each entry relates to a file, and they should be added as names with no extensions and relative to your book’s root folder. The title of each chapter will be inferred from the title in your files.

More about _toc.yml

You can specify more complex book configurations with your _toc.yml file. For example, you can specify parts, sections, and control custom titles. For more information about your book’s table of contents file, see Structure the Table of Contents.

Book content

A collection of text files make up your book’s content. These can be one of several types of files, such as markdown (.md), Jupyter Notebooks (.ipynb) or reStructuredText (.rst) files (see Types of content source files for a full list).

In the above example, there were two files listed: a markdown file and a Jupyter Notebook. We’ll cover each in the next section.

上一页

Create your first book

下一页

Create your book’s source files