render-puzzle-docs

用途：构建与渲染 jigsawR 项目的 Quarto 文档站点，供 GitHub Pages 使用。适用于内容变更后整站构建、迭代编辑时单页渲染、发布或 PR 前准备文档，以及排查 .qmd 渲染错误。\n\n输入：必填渲染模式（fresh、cached 或 single）；可选指定单个 .qmd 文件路径（单页模式）；可选是否在浏览器中打开结果。\n\n主要能力与用法：\n- 全新渲染：cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh，约 5-7 分钟，会清除 _freeze 与 _site 并重新执行全部 R 代码，适合内容变更或缓存过期。\n- 缓存渲染：cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh --cached，约 1-2 分钟，适合小改动。\n- 单页渲染：QUARTO_EXE="/mnt/c/Program Files/RStudio/resources/app/bin/quarto/bin/quarto.exe" 后接 "$QUARTO_EXE" render quarto/getting-started.qmd，约 30 秒。\n不确定缓存是否过期时默认用全新渲染。\n\n验证：检查 quarto/_site/index.html 是否存在且非空，导航链接、图片与 SVG 正常渲染。预览：cmd.exe /c start "" "D:\dev\p\jigsawR\quarto\_site\index.html"，若失败可改用 explorer.exe。\n\n限制与常见问题：冻结缓存过期需全新渲染；.qmd 使用了未安装的 R 包需先安装；pandoc 缺失需在 .Renviron 设置 RSTUDIO_PANDOC；代码块应加 #| label:；渲染失败可先 rm -rf quarto/_freeze quarto/_site；页面缺失需确认已在 _quarto.yml 中列出。相关技能：generate-puzzle、run-puzzle-tests、create-quarto-report。