概述¶

本节简要概述了构建 Jupyter Book 的主要组件和步骤。有关更深入的信息，请参阅本指南的其他页面。

安装 Jupyter Book¶

可以使用 pip 安装 Jupyter Book：

pip install -U jupyter-book

在本地构建 Jupyter Book 所需的一切将被安装。

Jupyter Book 的命令行界面¶

Jupyter Book 使用命令行界面来执行各种操作。例如，建造和清洁书籍。您可以运行以下命令查看哪些选项在您的控制下：

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.

有关 CLI 的更完整信息，请参见命令行界面。

书籍构建过程¶

构建一本 Jupyter Book 大致包括以下步骤：

创建你的书的内容。您可以用文件夹、文件和配置的集合来构造您的书。参见 Jupyter Book 的解剖。
构建你的书。使用 Jupyter Book 的命令行界面，您可以将页面转换为 HTML 或 PDF 图书。参见建立你的书。
在网上发布你的书。一旦你的书建好了，你就可以和别人分享了。最常见的是构建 HTML，并将其作为公共网站托管。参见在线发布您的书。

注解

我们将使用“book”这个词来描述本教程生成的输出，但是您也可以使用 Jupyter Book 来构建文章。阅读 Structure of an Article 了解更多信息。

Jupyter Book 的解剖¶

你需要做三件事来制作一本 Jupyter Book：

配置文件：_config.yml
目录文件：_toc.yml
你的书的内容

例如，考虑下面的文件夹结构，它组成了一个简单的 Jupyter Book。

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

我们将在下面简要介绍它们，您可以在本文档的其他地方找到关于它们的更多信息。

Book 的配置（`_config.yml`）¶

您的书的所有配置都在一个名为 _config.yml 的 YAML 文件中。

您可以为您的图书定义元数据(比如它的标题)，添加图书标识，打开不同的“交互式”按钮(比如一个 Binder 按钮，用于从 Jupyter Book 构建的页面)，等等。

下面是一个简单的 _config.yml 示例文件：

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

title：定义书的标题。它将会被展示在左侧的侧边栏。
logo：定义图书标识的图像文件的路径(它也会显示在侧边栏中)。
execute：包含控制执行和缓存的配置选项集合。
- execute_notebooks: "off" 告诉 Jupyter Book 不要执行任何它在构建书时发现的计算内容。默认情况下，Jupyter Book 会执行并缓存所有的图书内容。

更多关于 _config.yml

你可以用 _config.yml 文件做更多的事情。例如，您可以添加源存储库按钮或添加交互式数据可视化。获取 _config.yml 的完整字段列表，请参见配置参考。

Book 的目录（`_toc.yml`）¶

Jupyter Book 使用你的目录来定义你的书的结构。例如，你的章节，分章节等等。

这是一个包含一组页面的 YAML 文件，每个页面都链接到书中的一个文件。下面是上面显示的两个内容文件的示例。

# In _toc.yml
- file: landing-page
- file: page1

_toc.yml 中的每一项都指向单个文件。链接应该是相对于你的书的文件夹，没有扩展名。你可以将 TOC 文件的最顶层想象成书籍的章节(不包括登录页)。每一章的标题将从你文件的标题中推断出来。

第一个文件指定图书的登录页(在本例中，它是一个 markdown 文件)。登录页（landing page）是书籍内容层次结构中最高的页面。第二个文件指定图书的内容页(在本例中，它是一个 Jupyter Notebook)。

更多关于 _toc.yml

您可以使用 _toc.yml 指定更复杂的图书配置。例如，您可以指定 parts、sections 和控制 custom titles。关于书的目录文件的更多信息，请参见 Structure the Table of Contents。

书籍内容¶

一组文本文件构成了你的书的内容。这些文件可以是几种类型中的一种，例如 markdown (.md)、Jupyter notebook (.ipynb)或 reStructuredText (.rst)文件(请参阅内容源文件的类型以获得完整列表)。

在上面的例子中，列出了两个文件：一个 markdown 文件和一个 Jupyter Notebook。我们将在下一节中介绍它们。

概述¶