Agent-almanac render-puzzle-docs

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/render-puzzle-docs" ~/.claude/skills/pjt222-agent-almanac-render-puzzle-docs-7852aa && rm -rf "$T"

manifest: i18n/zh-CN/skills/render-puzzle-docs/SKILL.md

source content

渲染拼图文档

渲染 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:
```
以获得干净渲染