preview

预览

使用 Quarto 渲染并部署项目文档、报告和笔记本。

使用方法

如果缺少 _quarto.yml 或 .github/workflows/docs.yml，请先完成下面的设置步骤。

推送分支。CI 会自动渲染并部署。PR 预览 URL：https://<owner>.github.io/<repo>/pr-preview/pr-<number>/（私有仓库使用混淆后的域名，但路径结构相同）。使用 gh run list / gh run view 查看 CI 状态。

本地预览：quarto preview（支持热重载）。一次性构建：quarto render。

Quarto 项目设置

如果项目尚无 _quarto.yml，请先与用户确认计划，然后：

1. 检查 which quarto。如果本地未安装，请参阅 https://quarto.org/docs/get-started/，或使用 Workspace 技能获取预装 Quarto 的 devcontainer。
2. 将 assets/_quarto.yml 复制到项目根目录，并调整标题。
3. 创建包含 YAML 前置元数据（至少包含 title:）的 index.qmd。所有文档都使用 .qmd——这是 Quarto 的规范格式，也是获得完整工具支持的必要条件。
4. 将 _site/ 和 .quarto/ 添加到 .gitignore。
5. 每个子目录都需要有 index.qmd，否则其侧边栏链接会返回 404。

GitHub Pages 设置

设置此项，以通过 GitHub Pages 部署渲染后的文档，并提供 PR 预览。如果项目尚无 .github/workflows/docs.yml，请先与用户确认计划，然后：

1. 将 assets/docs.yml 复制到 .github/workflows/docs.yml。此工作流使用 Quarto 渲染、验证输出（出现引用损坏等警告时会失败），并支持 PR 预览部署。
2. Pages 必须从 gh-pages 分支提供服务，不能使用“GitHub Actions”工作流模式——该产物模型无法同时托管 PR 预览和主站点。

   gh api repos/{owner}/{repo}/pages -X POST --input - <<'EOF'
   {"build_type":"legacy","source":{"branch":"gh-pages","path":"/"}}
   EOF
   

3. 要求所有对 main 的更改都必须通过 CI 检查并提交 PR。此操作会覆盖现有的分支保护规则（文档）：

   gh api repos/{owner}/{repo}/branches/main/protection -X PUT --input - <<'EOF'
   {
     "required_status_checks": {"strict": false, "contexts": ["build-and-deploy"]},
     "enforce_admins": false,
     "required_pull_request_reviews": {"required_approving_review_count": 0},
     "restrictions": null
   }
   EOF