GitHub Pages

概述

GitHub Pages 是一个网站托管服务，使您能够基于托管在 GitHub 仓库中的源代码发布内容。

有三种方法可以将 Quarto 网站和文档发布到 GitHub Pages：

  1. 在本地计算机上渲染网站到 docs 目录，将渲染后的网站提交到 GitHub，然后配置您的 GitHub 仓库从 docs 目录发布。

  2. 使用 quarto publish 命令发布本地渲染的内容。

  3. 使用 GitHub Action 自动渲染您的文件（单个 Quarto 文档或 Quarto 项目），并在您推送源代码更改到仓库时发布生成的内容。

我们将在下面介绍每种方法，但首先是一个重要的前提条件：您需要在本地计算机上有一个与 GitHub 同步的 Git 仓库。发布网站的 URL 将由您的用户名和仓库名称组合而成（例如 https://username.github.io/reponame/）。

您可以选择为 GitHub Pages 站点配置 自定义域名，但在探索这一点之前，您应该先使用默认域名让您的站点运行起来。

渲染到 docs

使用 GitHub Pages 发布的最简单方法是渲染到 docs 目录，然后将该目录提交到您的仓库。如果您不想将渲染后的输出提交到版本控制中，请参阅下面的 Publish Command 讨论。

要开始，请更改您的项目配置以使用 docs 作为 output-dir。例如：

_quarto.yml
project:
  type: website
  output-dir: docs

然后，在仓库的根目录添加一个 .nojekyll 文件，告诉 GitHub Pages 不要使用 Jekyll（GitHub 默认的站点生成工具）对您发布的站点进行额外处理：

Mac/Linux 
Terminal
touch .nojekyll
Windows 
Terminal
copy NUL .nojekyll

现在，渲染您的站点并将其推送到 GitHub：

Terminal
quarto render
git add docs
git commit -m "Publish site to docs/"
git push

最后，配置您的 GitHub 仓库从 main 分支的 docs 目录发布：

一旦您进行了此配置更改，GitHub 将触发您的网站部署。每当您提交并推送到 main 时，您的站点也会更新。

Publish Command

quarto publish 命令是发布本地渲染的文档和网站的简便方法。在尝试使用 quarto publish（无论是本地还是通过 GitHub Action）之前，您应该确保按照下面的说明配置 Source Branch 和 Ignore Output。

Source Branch

在尝试发布之前，您应该确保仓库的 Source 分支是 gh-pages，并且站点目录设置为仓库根目录（/）。您可以在仓库的 Settings : Pages 中修改这些选项。例如，如果您已经有一个 gh-pages 分支：

如果您还没有 gh-pages 分支，可以按如下方式创建一个。首先，确保您已经使用 git status 将所有更改提交到当前工作分支。然后：

Terminal
git checkout --orphan gh-pages
git reset --hard # 确保在运行此命令之前所有更改都已提交！
git commit --allow-empty -m "Initialising gh-pages branch"
git push origin gh-pages

再次检查最后一个 git push 操作是否确实如前图所示设置了仓库的 Settings : Pages。例如，使用 git checkout main 返回到您的原始仓库分支。

Ignoring Output

需要注意的是，你不需要将你的 _site 或 _book 目录提交到版本控制中（如果你曾经这样做过，你会知道这会导致非常混乱的差异！）。在继续之前，你应该将项目的输出目录添加到 .gitignore 中。例如：

.gitignore
/.quarto/
/_site/

如果你已经将这些文件提交到源代码控制中，你可能需要显式地删除它们：

Terminal
git rm -r _site

Publishing

一旦您配置了源分支并更新了 .gitignore，导航到您的项目/git 仓库所在的目录，确保您不在 gh-pages 分支上，并执行 quarto publish 命令以发布到 GitHub Pages：

Terminal
quarto publish gh-pages

publish 命令将确认您是否要发布，渲染您的内容，将输出复制到一个特殊的 gh-pages 分支，将该分支推送到 GitHub，然后在部署完成后打开浏览器查看您的站点。

私有站点

如果您要发布到一个私有的（即受密码保护的）网站，那么 quarto publish 中等待您的站点可用后再打开浏览器的逻辑将无法正常工作。在这种情况下，您应该传递 --no-browser 选项来绕过此步骤：

Terminal
quarto publish gh-pages --no-browser

文档

要发布文档而不是网站或书籍，请提供文档的路径（请注意，您只能从给定的 GitHub 仓库发布一个文档）：

Terminal
quarto publish gh-pages document.qmd

选项

以下是 quarto publish gh-pages 的所有可用命令行选项：

选项 行为
--no-prompt 不提示确认发布操作。
--no-browser 发布后不打开浏览器。
--no-render 发布前不重新渲染。

GitHub Action

使用 quarto publish gh-pages 命令发布本地渲染的内容是最简单直接的发布方式。另一种选择是使用 GitHub Actions 来渲染和发布您的站点（如果您希望执行和/或渲染能从提交自动触发，您可能会更喜欢这种方式）。

有几种不同的方法来处理内容的渲染和发布。下面，我们将提供一个使用 GitHub Actions 发布的操作指南。有关各种方法的更多概念背景，请参阅关于 CI 渲染 的讨论。

冻结计算

为了确保 R、Python 和 Julia 代码仅在本地执行，请通过在 _quarto.yml 中添加以下内容，配置您的项目以使用 Quarto 的 冻结 功能：

_quarto.yml
execute:
  freeze: auto

现在，完全重新渲染您的站点：

Terminal
quarto render

如果您在项目中有可执行代码，您会注意到在项目的顶层创建了一个 _freeze 目录。此目录存储计算结果，并应将其提交到版本控制中。每当你更改包含可执行代码的 .qmd 文件时，它将在下一次渲染时自动重新运行，并且更新后的计算结果将存储在 _freeze 中。

请注意，另一种方法是作为 GitHub Action 的一部分执行代码。目前，我们将通过在本地执行代码并使用冻结来存储计算，使事情保持简单。然后，在下面，我们将介绍在 GitHub Action 中 执行代码。

发布操作

在配置发布操作之前，重要的是您先在本地运行一次 quarto publish gh-pages。这将创建后续 GitHub Action 调用所需的 _publish.yml 配置。为此，请从您的项目中运行以下命令：

quarto publish gh-pages

完成本地发布后，通过创建此 YAML 文件并将其保存到 .github/workflows/publish.yml 来为您的项目添加一个 publish.yml GitHub Action：

.github/workflows/publish.yml
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

每当您推送到仓库的 main 分支时，此操作都会运行。当您从仓库的 Actions 选项卡手动触发操作时，它也会运行。该操作将渲染您的内容并将其发布到 GitHub Pages，因此您需要确保 GitHub Actions 有权限写入您的仓库。这是通过在仓库 Settings 的 Actions 部分下勾选 Workflow permissions 中的 Read and write permissions 复选框来完成的。

完成此操作后，将所有新创建的文件（包括 _freeze 目录）检入您的仓库，然后推送到 GitHub。将为您的仓库创建一个 GitHub Pages 站点，每次您推送新更改到仓库时，它都会自动重建以反映更改。请查阅仓库 Settings 的 Pages 部分，查看您的站点的 URL 和发布状态。

执行代码

如果你愿意，你也可以配置一个GitHub Action来执行R、Python或Julia代码作为渲染的一部分。虽然这可能本能地看起来是最好的方法，但当你在像GitHub Actions这样的CI服务中执行代码时，请考虑以下要求：

  • 你需要在CI环境中重新构建所有依赖项（R、Python或Julia以及所需包的正确版本）。

  • 如果你的代码需要任何特殊权限（例如数据库或网络访问），这些权限也需要存在于CI服务器上。

  • 你的项目可能包含一些难以再次轻松执行的文档（例如几年前使用旧版本包的博客文章）。这些文档可能需要单独启用freeze以防止在CI上执行。

先决条件

确保你的代码可以在GitHub Action中执行的最佳方式是使用虚拟环境，如venv或renv与你的项目一起使用（下面我们将为每种环境提供示例操作）。如果你不熟悉使用这些工具，请查看关于在Quarto中使用虚拟环境的文章以了解更多信息。

一旦你决定在GitHub Action中执行代码，你可以从你的_quarto.yml配置中移除上面提到的freeze: auto。请注意，如果你想有选择地对某些文档或目录使用freeze，这仍然是可能的（对于一个目录，在该目录中创建一个_metadata.yml文件，并在其中指定你的freeze配置——这是Quarto对博客项目中的posts文件夹默认执行的操作）。

示例：使用 venv 的 Jupyter

以下是一个完整的 GitHub Action 示例，它安装 Python、Jupyter 和来自 requirements.txt 的包依赖项，然后执行代码并将输出渲染到 GitHub Pages：

.github/workflows/publish.yml
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto 发布

jobs:
  构建与部署:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: 检出仓库
        uses: actions/checkout@v4

      - name: 设置 Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: 安装 Python 及依赖项
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
          cache: 'pip'
      - run: pip install jupyter
      - run: pip install -r requirements.txt

      - name: 渲染并发布
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

示例：使用 renv 的 Knitr

以下是一个完整的 GitHub Action 示例，它安装 R 和 renv.lock 中的包依赖项，然后执行代码并将输出渲染到 GitHub Pages：

.github/workflows/publish.yml
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.2.0'

      - name: Install R Dependencies
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

附加选项

在一个较大的 GitHub 仓库中，Quarto 项目可能不在顶层目录中。在这种情况下，可以在 publish 动作的调用中添加一个 path 输入。例如：

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: gh-pages
    path: subdirectory-to-use
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

默认情况下，quarto publish 会在发布前重新渲染你的项目。然而，如果你将渲染后的输出存储在版本控制中，你不需要 GitHub Action 重新渲染项目。在这种情况下，可以在 publish 动作中添加选项 render: false：

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: gh-pages
    render: false
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

查看 Quarto publish action 的完整定义，了解更多高级选项。

用户站点

除了创建与各种仓库关联的站点外，你还可以创建一个从你的根用户域（例如 https://username.github.io）提供的用户站点。这是发布博客或个人主页的理想场所。要创建用户站点：

  1. 创建一个名为 username.github.io（其中 “username” 是你的 GitHub 用户名）的 Git 仓库，并将其同步到你的本地机器。

  2. 按照 Source Branch 中的描述，将用户站点的 Source 分支设置为 gh-pages。