---

name: render-puzzle-docs description: > 渲染 jigsawR 的 Quarto 文档站点用于 GitHub Pages。支持全新渲染（清除缓存）、 缓存渲染（更快）和单页渲染。使用捆绑的渲染脚本或从 WSL 直接调用 quarto.exe。 适用于内容更改后构建完整站点、迭代编辑时渲染单页、为发布或 PR 准备文档， 以及调试 Quarto .qmd 文件中的渲染错误。 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: jigsawr complexity: basic language: R tags: jigsawr, quarto, documentation, github-pages, rendering locale: zh-CN source_locale: en source_commit: 6f65f316 fence_basis_commit: 6f65f316 translator: claude-sonnet-4-6 translation_date: 2026-03-16

渲染拼图文档

渲染 jigsawR 的 Quarto 文档站点。

适用场景

• 内容更改后构建完整文档站点
• 迭代编辑时渲染单个页面
• 为发布或 PR 准备文档
• 调试 Quarto .qmd 文件中的渲染错误

输入

• 必需：渲染模式（fresh、cached 或 single）
• 可选：指定 .qmd 文件路径（用于单页模式）
• 可选：是否在浏览器中打开结果

步骤

第 1 步：选择渲染模式

模式	命令	耗时	使用时机
全新	bash inst/scripts/render_quarto.sh	~5-7 分钟	内容更改、缓存过时
缓存	bash inst/scripts/render_quarto.sh --cached	~1-2 分钟	微调编辑、缓存有效
单页	直接调用 quarto.exe	~30 秒	迭代编辑单个页面

预期结果： 根据当前情况选择渲染模式：内容更改或缓存过时时选全新渲染，微调编辑时选缓存渲染，迭代编辑单个页面时选单页渲染。

失败处理： 如果不确定缓存是否过时，默认使用全新渲染。耗时更长但保证输出正确。

第 2 步：执行渲染

全新渲染（清除 _freeze 和 _site，重新执行所有 R 代码）：

cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh

缓存渲染（使用现有 _freeze 文件）：

cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh --cached

单页渲染（直接渲染一个 .qmd 文件）：

QUARTO_EXE="/mnt/c/Program Files/RStudio/resources/app/bin/quarto/bin/quarto.exe"
"$QUARTO_EXE" render quarto/getting-started.qmd

预期结果： 渲染完成无错误。输出在 quarto/_site/。

失败处理：

• 检查 .qmd 代码块中的 R 代码错误（查找 #| label: 标记）
• 验证 pandoc 是否可通过 RSTUDIO_PANDOC 环境变量访问
• 尝试清除缓存：rm -rf quarto/_freeze quarto/_site
• 检查 .qmd 文件中使用的所有 R 包是否已安装

第 3 步：验证输出

ls -la /mnt/d/dev/p/jigsawR/quarto/_site/index.html

确认站点结构：

• quarto/_site/index.html 存在
• 导航链接正确解析
• 图片和 SVG 文件正确渲染

预期结果： index.html 存在且非空。导航链接可解析，图片/SVG 在浏览器中正确渲染。

失败处理： 如果 index.html 缺失，渲染可能静默失败。使用详细输出重新运行并检查 .qmd 代码块中的 R 代码错误。如果只有部分页面缺失，验证那些 .qmd 文件是否列在 _quarto.yml 中。

第 4 步：预览（可选）

在 Windows 浏览器中打开：

cmd.exe /c start "" "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html"

预期结果： 文档站点在 Windows 默认浏览器中打开以供视觉检查。

失败处理： 如果从 WSL 执行 cmd.exe /c start 命令失败，尝试 explorer.exe "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html"。或者在浏览器中手动导航到该文件。

验证清单

• quarto/_site/index.html 存在且非空
• 控制台输出中无渲染错误
• 所有 R 代码块成功执行（检查错误消息）
• 页面间导航正常
• 所有 .qmd 文件的代码块都有 #| label: 以获得干净输出

常见问题

• 过时的 freeze 缓存：如果 R 代码更改了，使用全新渲染重新生成 _freeze 文件
• 缺少 R 包：Quarto .qmd 文件可能使用了不在 renv 中的包；先安装它们
• 找不到 Pandoc：确保 .Renviron 中设置了 RSTUDIO_PANDOC
• 渲染时间长：全新渲染需要 5-7 分钟（14 页含 R 执行）；迭代时使用缓存模式
• 代码块标签：所有 R 代码块应有 #| label: 以获得干净渲染

相关技能

• generate-puzzle — 生成文档中引用的拼图输出
• run-puzzle-tests — 确保文档中的代码示例正确
• create-quarto-report — 通用 Quarto 文档创建