GitHub Pages 和 Actions

一旦你的内容上传到 GitHub，你可以轻松地将它托管为一个 GitHub Pages 网站。这是一个服务，GitHub 将你的静态文件托管起来，就像它们是一个独立的网站一样。使用 GitHub Actions 部署构建的 HTML 文件是开始在 GitHub Pages 上使用 Jupyter Book 的最快捷方式。

GitHub Actions 是一个允许你在 GitHub 上自动执行任务的工具。它用于各种任务，例如测试、发布包和持续集成。

请注意，如果你没有在 GitHub 上托管你的书籍，或者你希望使用另一个用户友好的服务来自动构建它，请参阅在 Netlify 上发布你的书籍的指南。

Note

在使用 GitHub Actions 自动托管你的 Jupyter Books 之前，你应该熟悉它们。有关更多信息，请参阅 GitHub Actions 文档。

要使用 GitHub Actions 构建你的书籍，首先需要为你的项目启用 GitHub Pages。仓库的 GitHub Pages 设置可以在 Settings -> Pages 中找到，其中 Source 应设置为 GitHub Actions。

接下来，你需要设置一个工作流来执行以下操作：

• 当 master（或任何其他）分支上有推送事件时激活，该分支包含你的最新书籍内容。

• 安装 Jupyter Book 以及构建你的书籍所需的任何依赖项。

• 构建你的书籍的 HTML。

• 使用 actions/deploy-pages 操作将该 HTML 上传到 GitHub Pages。

Note

确保你使用的是 Jupyter Book >= 1.0.0。要使用最新版本，运行 pip install -U jupyter-book。

Tip

你可以使用 Jupyter Book cookiecutter 快速创建一个已经包含 GitHub Actions 工作流文件的书籍模板，该文件用于自动将你的书籍部署到 GitHub Pages：

jupyter-book create --cookiecutter mybookpath/

有关更多帮助，请参阅 Jupyter Book cookiecutter GitHub 仓库，或运行：

jupyter-book create --help

以下是一个简单的 YAML 配置，用于将位于 GitHub 仓库根目录中的 Jupyter Book 发布到 GitHub Pages 的 GitHub Action：

name: deploy-book

# 当 master 或 main 分支发生变化时运行
on:
  push:
    branches:
    - master
    - main
    # 如果你的 git 仓库在某些子文件夹中包含 Jupyter Book 以及无关的文件，
    # 你可以设置仅当该特定文件夹中的文件被修改时才运行。
    #
    # paths:
    # - some-subfolder/**

# 此作业安装依赖项，构建书籍，并将其推送到 `gh-pages`
jobs:
  deploy-book:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    steps:
    - uses: actions/checkout@v3

    # 安装依赖项
    - name: Set up Python 3.11
      uses: actions/setup-python@v4
      with:
        python-version: 3.11

    - name: Install dependencies
      run: |
        pip install -r requirements.txt

    # （可选）在运行之间缓存已执行的 notebook
    # 如果你有以下配置：
    # execute:
    #   execute_notebooks: cache
    - name: cache executed notebooks
      uses: actions/cache@v3
      with:
        path: _build/.jupyter_cache
        key: jupyter-book-cache-${{ hashFiles('requirements.txt') }}

    # 构建书籍
    - name: Build the book
      run: |
        jupyter-book build .

    # 将书籍的 HTML 作为工件上传
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v2
      with:
        path: "_build/html"

    # 将书籍的 HTML 部署到 GitHub Pages
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v2

有关 GitHub Pages 的更多信息，例如配置自定义域名，请访问 GitHub Pages 文档。