在线发布你的书籍

在线发布你的书籍#

一旦你为你的书籍构建了 HTML，你就可以将它托管到线上。 最好的方式是使用托管静态网站的服务（因为这就是你用 Jupyter Book 创建的内容）。 在本教程中，我们将介绍如何使用 GitHub Pages 这个流行的免费在线托管平台来在线发布你的书籍。

为你的书籍创建一个在线仓库#

为了将你托管的书籍与你书籍的源内容连接起来，你应该将书籍的源内容放在一个公共仓库中。本节描述了一种创建你自己的 GitHub 仓库并将你的书籍内容添加到其中的方法。

  1. 首先，登录到 GitHub，然后转到“创建新仓库”页面：new

  2. 接下来，为你的在线仓库命名并添加描述。将你的仓库设为公开，并且不要初始化 README 文件，然后点击“创建仓库”。

  3. 现在，将（当前为空的）在线仓库克隆到你本地计算机上的某个位置。你可以通过命令行执行以下操作：

    git clone https://github.com/<my-org>/<my-repository-name>

  4. 将你所有的书籍文件和文件夹复制到这个新克隆的仓库中。例如，如果你在本地使用 jupyter-book create mylocalbook 创建了你的书籍，而你的新仓库名为 myonlinebook，你可以通过命令行执行以下操作：

    cp -r mylocalbook/* myonlinebook/

  5. 现在你需要同步你的本地和远程（即在线）仓库。你可以通过以下命令来完成：

    cd myonlinebook
git add ./*
git commit -m "adding my first book!"
git push

使用 GitHub Pages 在线发布你的书籍#

我们刚刚将书籍的源文件推送到了我们的 GitHub 仓库中。 这使得它对你或其他人都公开可见。

接下来，我们将在线上发布我们书籍的构建产物，以便它被渲染为一个网站。

使用 GitHub Pages 最简单的方式是使用 ghp-import 包。ghp-import 是一个轻量级的 Python 包，它使得将 HTML 内容推送到 GitHub 仓库变得容易。

ghp-import 的工作原理是将你构建的书籍的所有内容（即 _build/html 文件夹）复制到一个名为 gh-pages 的分支中，并将其推送到 GitHub。ghp-import 会自动为你创建并填充 gh-pages 分支。要使用 ghp-import 通过 GitHub Pages 在线托管你的书籍，请按照以下步骤操作：

Note

在执行以下步骤之前，确保为你的书籍的每一页都构建了 HTML（参见 上一节）。你的书籍的 _build/html 文件夹中应该有一组 HTML 文件。

  1. 安装 ghp-import

    pip install ghp-import

  2. 更新你的 GitHub Pages 站点的设置：

    a. 使用 gh-pages 分支来托管你的网站。

    b. 如果你在自己的仓库中构建书籍，选择根目录 /。 如果你用 jupyter-book 构建文档，选择 /docs 目录。

  3. 从你的书籍根目录的 main 分支（应该包含 _build/html 文件夹）调用 ghp-import 并指向你的 HTML 文件，如下所示：

    ghp-import -n -p -f _build/html

Warning

确保你包含了 -n - 这告诉 GitHub 不要 使用 Jekyll 构建你的书籍，因为我们已经构建了 HTML！如果你不这样做，你可能会看到你的部署内容出现 404 未找到。

通常几分钟后你的站点应该可以在以下网址查看：https://<user>.github.io/<myonlinebook>/。如果没有，请检查你的仓库设置中的 Options -> GitHub Pages，确保 gh-pages 分支被配置为 GitHub Pages 的构建源，或者找到 GitHub 为你构建的网址。

要更新你的在线书籍，请在你的仓库的 main 分支上对你的书籍内容进行更改，使用 jupyter-book build mybookname/ 重新构建你的书籍，然后像之前一样使用 ghp-import -n -p -f mylocalbook/_build/html 将新构建的 HTML 推送到 gh-pages 分支。

Warning

注意来自 ghp-import GitHub 仓库 的这个警告：

“…ghp-import 将会销毁你的 gh-pages 分支…并且假设 gh-pages 分支是 100% 衍生的。如果你使用这个脚本，千万不要在 gh-pages 分支中手动编辑文件…”