构建你的书籍

构建你的书籍#

一旦你添加了内容并配置了你的书籍，就可以为你的书籍构建输出了。我们将使用 jupyter-book build 命令行工具来完成这个任务。

目前，支持两种类型的输出：你的书籍的HTML网站，以及从书籍HTML构建的包含所有页面内容的PDF。在本教程中，我们将重点介绍构建HTML输出。

为了构建每个页面的HTML，你应该已经按照概述和创建模板书籍中的步骤操作。你应该在你的 mybookname/ 文件夹中有一些笔记本/Markdown文件，一个定义了书籍结构的 _toc.yml 文件，以及在 _config.yml 文件中的任何配置。

现在你的书籍内容已经放置在书籍文件夹中，并且你已经在 _toc.yml 中定义了书籍的结构，你可以为你的书籍构建HTML了。

运行以下命令：

jupyter-book build mybookname/

这将使用一个静态网站生成器生成一个功能齐全的HTML网站。该网站将被放置在 _build/html 文件夹中，类似如下：

mybookname
 └──_build
    └── html
       ├── _images
       ├── _static
       ├── index.html
       ├── intro.html
       ...

这些是独立网站的静态文件！它们包含了在浏览器中查看你的书籍所需的所有HTML和其他资源。

你可以通过导航到该文件夹并使用浏览器打开 html 文件来打开网站中的页面。

Note

你也可以使用 jb 作为 jupyter-book 的简写。例如：jb build mybookname/。

此时，你已经创建了一组Jupyter笔记本、Markdown文件和配置文件，包括 _toc.yml 和 _config.yml。这些文件是你的源文件。源文件包含了Jupyter Book构建你的书籍所需的所有内容和配置。

此外，你已经在 _build 文件夹中创建了一组输出文件。 _build 文件夹包含了你所有静态网站的构建文件。构建文件包含了Jupyter Book的 build 命令的所有输出。这些文件仅用于在浏览器中查看内容或与他人分享。

发布你的书籍的最佳实践是使用不同的分支来管理源文件和构建文件。例如，你可以让git在 main 分支上忽略你的 _build 文件夹，并将 _build 文件夹中的输出推送到一个名为 gh-pages 的分支。我们稍后会介绍其中的一些内容。

关于页面缓存的提示

默认情况下，Jupyter Book只会为自上次构建书籍以来更新的页面构建HTML。

如果你想强制Jupyter Book重新构建某个特定页面，你可以编辑书籍文件夹中的相应文件，或者删除 _build/html 文件夹中该页面的HTML文件。

你也可以使用 --all 选项来指示进行完全重建：

jupyter-book build --all mybookname/

要预览你的书籍，你可以打开生成的HTML文件在你的浏览器中查看。你可以双击本地文件夹中的html文件，或者在浏览器导航栏中输入文件的绝对路径，并在开头添加 file://（例如 file://Users/my_path_to_book/_build/index.html）。

查看从你创建的Markdown页面生成的网页。注意你插入的链接是如何自动解析到正确位置的。这是你如何保持书籍各部分之间一致指向的方式。

现在你已经从你的演示书籍构建了一个简单的HTML网站，我们将创建一些新内容，以便你能掌握添加新文件的方法。请参阅创建你自己的内容文件获取下一步。