Quarto Pub

概述

Quarto Pub 是一个免费的发布服务，适用于使用 Quarto 创建的内容。Quarto Pub 非常适合博客、课程或项目网站、书籍、演示文稿和个人爱好网站。

需要注意的是，所有发布到 Quarto Pub 的文档和网站都是公开可见的。您应该只发布您希望公开分享的内容。

有两种方式可以将内容发布到 Quarto Pub（下面将详细介绍这两种方式）：

  1. 使用 quarto publish 命令发布本地渲染的内容（这是开始时推荐的方法）。

  2. 如果您使用 GitHub，可以使用 GitHub Action 在代码更改时自动渲染您的项目并发布生成的内容。

在尝试首次发布之前，请确保您已经创建了一个免费的 Quarto Pub 账户。

Note

Quarto Pub 网站是公开可见的，大小不能超过 100 MB，每月带宽有 软 限制为 10 GB。如果您希望对用户进行身份验证、托管更大的网站或使用自定义域名，请考虑使用 Netlify 等专业的网页发布服务。

发布命令

quarto publish 命令是发布本地渲染内容的简便方式。从项目所在的目录中，执行 quarto publish 命令以发布到 Quarto Pub：

终端
quarto publish quarto-pub

如果你之前未曾发布到 Quarto Pub，发布命令将提示你进行身份验证。确认要发布后，你的内容将被渲染并部署，然后浏览器将打开以查看你的站点。

_publish.yml

_publish.yml 文件用于指定发布目的地。每次执行 quarto publish 命令时，此文件会自动创建（或更新），并位于项目或文档目录中。

发布内容的平台、ID 和 URL 在 _publish.yml 中指定。例如：

- source: project
  quarto-pub:
    - id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://njones.quarto.pub/blog"

如果你有一个现有的 Quarto Pub 站点并希望发布到该站点，你应该手动创建一个类似于上述示例的 _publish.yml 文件，但需使用你站点的适当 id 和 url 值。

账户信息不会存储在 _publish.yml 中，因此适合将其检入版本控制并与多个发布者共享。

选项

你可以通过提供以下命令行选项来自定义 quarto publish 的行为：

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

要发布文档而非网站或书籍，请提供文档的路径：

终端
quarto publish quarto-pub document.qmd

管理网站

如果您想更改已发布网站的“slug”（或 URL 路径）或完全删除网站，可以使用位于 https://quartopub.com 的网站管理界面，该界面将显示您所有已发布的网站列表：

点击一个网站以导航到管理页面，您可以在该页面上更改 slug、将网站设为账户的默认网站或完全删除网站：

用户默认网站

除了将文档和网站发布到 Quarto Pub 子域内的路径（例如 https://username.quarto.pub/mysite/）之外，您还可以将其中一个网站指定为用户导航到您的主子域时看到的默认网站（例如 https://username.quarto.pub）。这是发布博客或个人主页的理想位置。

要将其中一个网站提升为默认网站，请访问您的管理页面 https://quartopub.com，导航到您要提升的网站，勾选 默认网站 选项，然后 保存 您的修改选项：

多个账户

如果您有多个 Quarto Pub 账户，了解在 CLI 界面（quarto publish）中使用账户与在浏览器中使用账户（用于身份验证和管理网站）之间的关系非常重要。

在使用 quarto publish 时，有两种情况会启动网络浏览器：

  1. 当您需要授权 Quarto CLI 访问您的账户时。
  2. 发布后打开已发布网站的管理页面。

在使用 Quarto Pub 账户从 CLI 发布之前，您应该始终确保在默认网络浏览器中登录到该账户。这确保了当 CLI 启动浏览器时，它会绑定到正确的 Quarto Pub 账户。

访问令牌

当您使用 quarto publish 发布到 Quarto Pub 时，会使用访问令牌来授予发布到您账户的权限。如果没有可用的访问令牌用于发布操作，Quarto CLI 将自动启动浏览器以进行授权：

$ quarto publish quarto-pub
? 授权 (Y/n) › 
❯ 为了将内容发布到 Quarto Pub，您需要
  授权您的账户。请确保您已登录到
  正确的 Quarto Pub 账户，
  然后在默认网络浏览器中按 Enter 或
  'Y' 进行授权。

授权将启动您的默认网络浏览器以确认您希望允许从 Quarto CLI 进行发布。访问令牌将由 Quarto CLI 生成并本地保存。您可以使用 quarto publish accounts 命令列出和删除保存的账户：

$ quarto publish accounts
 ? 管理发布账户
 ❯ ✔ Quarto Pub: jj@rstudio.com
   ✔ Netlify: jj@rstudio.com
 ❯ 使用箭头键和空格键指定
   您希望删除的账户。按
   Enter 确认您希望保留的账户列表。

您还可以从管理界面 https://quartopub.com 查看（并撤销）访问令牌：

在此界面中，您将看到从 Quarto CLI 创建的任何令牌。如果您不再希望其处于活动状态，可以撤销此令牌。点击 新建令牌 按钮以创建额外的令牌，这些令牌可用于非交互式发布（例如从 CI 服务）：

一旦你有了访问令牌，你可以通过定义 QUARTO_PUB_AUTH_TOKEN 环境变量将其与 quarto publish 一起使用。例如：

Terminal
# 在 https://quartopub.com/profile/ 创建的令牌
export QUARTO_PUB_AUTH_TOKEN="qpa_k4yWKEmlu5wkvx173Ls"

# 发布到 _publish.yml 中指定的 quarto-pub 站点
quarto publish quarto-pub

有关 quarto publish 非交互式使用的更多详细信息，请参阅 使用 CI 发布 的文章。

GitHub Action

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

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

发布记录

在尝试使用 GitHub Action 发布之前，你应该至少完成了一次使用 发布命令（如上所述）的发布。这次发布将创建一个 _publish.yml 文件，记录 GitHub Action 将使用的发布目标。例如：

- source: project
  quarto-pub:
    - id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://njones.quarto.pub/blog"

你也可以手动创建一个类似于上面示例的 _publish.yml 文件，但需要为你的站点填写适当的 id 和 url 值。

在你有一个指示发布目标的 _publish.yml 文件之前，不要继续下一步。

冻结计算

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

_quarto.yml
execute:
  freeze: auto

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

Terminal
quarto render

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

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

发布操作

通过创建此 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
    steps:
      - name: 检出仓库
        uses: actions/checkout@v4 

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

      - name: 渲染并发布 
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: quarto-pub
          QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}

Quarto Pub 凭证

最后一步是使用发布所需的凭证配置你的 GitHub Action。为此，你需要创建一个 Quarto Pub 个人访问令牌，然后配置你的 GitHub Action 以能够读取它：

  1. 如果你还没有访问令牌，请前往 Quarto Pub 的 账户资料页面，点击 新建令牌 创建一个令牌。为这个令牌起一个容易记住的名字，并将其复制到剪贴板。

  2. 将 Quarto Pub 访问令牌添加到你的仓库的 Action Secrets（可在仓库 设置 中访问）。你会在右上角看到一个 新建仓库密钥 按钮：

    点击该按钮，并将步骤1中的个人访问令牌作为名为 QUARTO_PUB_AUTH_TOKEN 的密钥添加：

忽略输出

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

.gitignore
/.quarto/
/_site/

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

Terminal
git rm -r _site

提交以发布

一旦你指定了发布操作和 Quarto Pub 凭证，并将更新后的仓库（包括 _freeze 目录）推送到 GitHub，你的操作将在此及后续提交中运行，自动渲染并发布到 Quarto Pub。

执行代码

如果你愿意，你也可以配置一个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 中的包依赖项，然后执行代码并将输出渲染到 Quarto Pub：

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

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    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: quarto-pub
          QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}

示例：使用 renv 的 Knitr

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

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

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 检出仓库
        uses: actions/checkout@v4 

      - name: 设置 Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        
      - name: 安装 R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.2.0'
      
      - name: 安装 R 依赖项 
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1
      
      - name: 渲染并发布
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: quarto-pub
          QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}

其他选项

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

- name: 渲染并发布
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: quarto-pub
    path: 要使用的子目录
    QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}

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

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: quarto-pub
    render: false
    QUARTO_PUB_AUTH_TOKEN: ${{ secrets.QUARTO_PUB_AUTH_TOKEN }}