创建模板书籍

创建模板书籍#

既然我们理解了书籍的结构，让我们创建一个示例书籍来学习。

快速生成示例书籍#

Jupyter Book 自带了一个轻量级的示例书籍，帮助你理解书籍的结构。 通过运行以下命令创建一个示例书籍：

$ jupyter-book create mynewbook/

这将生成一个迷你 Jupyter Book，你可以在本地构建和探索。它会为你做出一些决定，你可以在 _config.yml 中探索书籍的配置，在 _toc.yml 中探索其结构。将这本书作为灵感，或作为起点进行工作。

Jupyter Book 的结构#

构建 Jupyter Book 需要三样东西，每一样都在运行 jupyter-book create 时创建了：

  • 配置文件 (_config.yml)

  • 目录文件 (_toc.yml)

  • 书籍内容

例如，看看你刚刚创建的书籍：

$ tree mybookname
mybookname/
├── _config.yml
├── _toc.yml
├── intro.md
├── logo.png
├── markdown-notebooks.md
├── markdown.md
├── notebooks.ipynb
├── references.bib
└── requirements.txt

里面有一些额外的文件，我们包括它们是为了展示一些新功能，但必需的部分是 _toc.yml、_config.yml 和内容文件。

我们将在下面简要介绍每个部分，你可以在本文件的其他地方找到更多信息。

书籍配置 (_config.yml)#

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

你可以为书籍定义元数据（例如标题）、添加书籍标志、开启不同的“互动”按钮（例如为基于 Jupyter Notebook 构建的页面添加 Binder 按钮），等等。

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

# 在 _config.yml 中
title: 我的示例书籍
author: Jupyter Book 社区
logo: logo.png
execute:
  execute_notebooks: force

# 添加一个 bibtex 文件，以便我们可以创建引用
bibtex_bibfiles:
  - references.bib

  • title: 定义书籍的标题。它将显示在左侧边栏中。

  • author: 为你的书籍模板添加作者姓名，用于归属。

  • logo: 定义书籍标志的图像文件路径（它也将显示在边栏中）。

  • execute: 包含一组配置选项，用于控制 执行和缓存。

    • execute_notebooks: "force" 告诉 Jupyter Book 强制执行每次构建书籍时所有的计算内容。默认情况下，Jupyter Book 执行并缓存所有书籍内容。

  • bibtex_bibfiles: 是一个部分，用于定义 Jupyter Book 的参考文献文件。 这个配置为你的书籍激活引用（参见 开始使用引用 以开始使用引用和参考文献）。

更多关于 _config.yml

你可以用 _config.yml 文件做更多的事情。例如，你可以 添加源仓库按钮 或添加 Interactive data visualizations。有关 _config.yml 的完整字段列表，请参阅 配置参考。

查看配置文件中的其他内容，并参考本文件中的页面，看看它们的作用。

目录 (_toc.yml)#

Jupyter Book 使用你的目录文件来定义书籍的结构。 例如，你的章节、子章节等。

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

# 在 _toc.yml 中
format: jb-book
root: intro
chapters:
- file: markdown
- file: notebooks
- file: markdown-notebooks

_toc.yml 以 format 如 jb-article 或 jb-book 排列。 root 项被视为落地页（用于 html 构建），并用作前言（用于 latex 构建）。 对于 jb-book，后续章节可以在 yml 文件的 chapters: 部分添加。

每个条目关联到一个文件，它们应该以无扩展名和相对于书籍根文件夹的相对路径添加。 每个章节的标题将从你的文件中推断出来。

更多关于 _toc.yml

你可以用 _toc.yml 文件指定更复杂的书籍配置。例如，你可以指定部分、节，并控制自定义标题。有关书籍目录文件的更多信息，请参阅 目录结构。

书籍内容#

一系列文本文件构成了你书籍的内容。这些可以是多种类型的文件之一，如 markdown (.md)、Jupyter Notebooks (.ipynb) 或 reStructuredText (.rst) 文件（参见 内容源文件类型 以获取完整列表）。

在上面的示例中，列出了三个文件：

  • 一个 Markdown 文件（markdown.md）

  • 一个 Jupyter Notebook（notebooks.ipynb）

  • 一个 MyST Markdown Notebook（markdown-notebooks.md）

我们将在下一节中逐一介绍。

内容文件#

下面是对Jupyter Book中几种主要内容文件的简要描述。

Markdown 文件（.md）#

Markdown 是一种标记语言的例子——一种使用额外字符和语法来赋予文本额外意义（例如，使用 **bold** 表示 粗体）的文本结构化方式。 它在许多不同的技术平台上非常流行且广泛使用。

Markdown 文件有细微的变化，通常称为 Markdown 的变种。 Jupyter Book 支持两种 Markdown 变种：

让我们来看看模板书中一个 Markdown 文件的例子，intro.md：

# 欢迎来到你的 Jupyter Book

这是一本小型的示例书，让你感受一下书的内容是如何结构的。

:::{note}
这里是一个笔记！
:::

这里是代码块：

```
e = mc^2
```

查看与本书捆绑的内容页面以了解更多。

上面你看到了几种不同的结构：

  • # 符号表示 章节标题 在 CommonMark Markdown 中。 它们定义了本页的章节标题，例如。

  • :::{note} 是 MyST Markdown 中的 指令。 它渲染成这样：

    Note

    我是一个笔记！

  • ``` 表示 CommonMark Markdown 中的 代码块。 它渲染成这样：

    e=mc^2

所有内容文件必须有一个页面标题（指定为第一个标题）。所有后续标题必须线性增加（所以不能从 H1 跳到 H3）。参见 所有内容类型的规则 了解更多所有内容必须遵守的规则。

有关 MyST Markdown 的更多信息以及你可以用它做的所有事情，请参见 MyST Markdown 概述。

Jupyter Notebooks（.ipynb）#

我们将注意到的另一种内容类型是 Jupyter Notebook，以 .ipynb 结尾。 Jupyter Notebooks 结合了计算内容和叙述内容。 每个笔记本都与一个 内核（即 Python、R、Julia 等）相关联，该内核定义了用于执行笔记本计算内容的语言。

默认情况下，当 Jupyter Book 构建你的书时，笔记本将被执行并且它们的输出将被缓存。在后续构建中，只有代码发生变化的笔记本页面才会重新执行。

笔记本生成的任何输出都将插入到你构建的书中（尽管它们可能不在你的输入笔记本中）。这样你就不需要将笔记本的输出与你的仓库一起存储。参见 执行并缓存您的页面 了解更多信息。

作为你书中的一部分，你可以用笔记本内容做许多其他有趣的事情。我们建议查看 格式化代码输出 以及 Interactive data visualizations 开始使用 Jupyter Notebooks。

MyST Markdown Notebooks（.md 和其他文本格式）#

最后，你可以 结合 Jupyter Notebook 和文本格式与 Jupyter Book。 这允许你完全用文本编写 Jupyter Notebook 的结构。 这需要使用一个特殊的 YAML 元数据块，该块告诉 Jupyter Book（通过一个名为 Jupytext 的工具）为页面创建一个笔记本并执行其内容。

有关 MyST Markdown 笔记本的更多信息，请参见 完全用 Markdown 编写的笔记本。

下一步：构建你的书#

现在你已经有了 Jupyter Book 的文件夹结构，你可以为书的每一页创建 HTML（或 PDF）。下一节将介绍这一点。