# Render Puzzle Docs

> Render the jigsawR Quarto documentation site for GitHub Pages. Supports fresh renders (clearing cache), cached renders (faster), and single-page renders. Uses the bundled render script or direct quarto.exe invocation from WSL. Use when building the full site after content changes, rendering a single page during iterative editing, preparing documentation for a release or PR, or debugging render errors in Quarto .qmd files.

- Skill: `pjt222/render-puzzle-docs-9` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pjt222/render-puzzle-docs-9`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/render-puzzle-docs-9/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/render-puzzle-docs-9

---


# 渲拼文

渲 jigsawR Quarto 文站。

## 用

- 容變後建全站
- 漸編時渲一頁
- 為發或 PR 備文
- 除 Quarto .qmd 渲錯

## 入

- **必**：渲模（`fresh`、`cached`、`single`）
- **可**：特 .qmd 路（單頁模）
- **可**：果開於瀏覽乎

## 行

### 一：擇渲模

| Mode | Command | Duration | Use when |
|---|---|---|---|
| Fresh | `bash inst/scripts/render_quarto.sh` | ~5-7 min | Content changed, cache stale |
| Cached | `bash inst/scripts/render_quarto.sh --cached` | ~1-2 min | Minor edits, cache valid |
| Single | Direct quarto.exe | ~30s | Iterating on one page |

得：渲模按況選：fresh 為容變或舊快取、cached 為微編、single 為迭一頁。

敗：未定快取舊乎→默 fresh。費時而保正出。

### 二：執渲

**Fresh 渲**（清 `_freeze` 與 `_site`、重執諸 R 碼）：

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

**Cached 渲**（用現 `_freeze` 檔）：

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

**單頁**（直渲一 .qmd 檔）：

```bash
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 包皆裝

### 三：驗出

```bash
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`。

### 四：預（可）

於 Windows 瀏覽開：

```bash
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 碼變、用 fresh 渲重生 `_freeze` 檔
- **缺 R 包**：Quarto .qmd 或用 renv 外包；先裝
- **Pandoc 不見**：確 `RSTUDIO_PANDOC` 設於 `.Renviron`
- **長渲時**：Fresh 渲費 5-7 分（14 頁含 R 執）；迭時用 cached 模
- **碼塊標**：諸 R 碼塊應有 `#| label:` 為潔渲

## 參

- `generate-puzzle` — 生文中所引拼出
- `run-puzzle-tests` — 確文中碼例正
- `create-quarto-report` — 通 Quarto 文建