# 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-5` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pjt222/render-puzzle-docs-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/render-puzzle-docs-5/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-5

---


# 渲拼之文檔

渲 jigsawR 之 Quarto 文檔站。

## 用時

- 內變後建全文檔站乃用
- 於迭編時渲單頁乃用
- 為釋或 PR 備文檔乃用
- 於 Quarto .qmd 之文中察渲誤乃用

## 入

- **必要**：渲模（`fresh`、`cached`、或 `single`）
- **可選**：具體 .qmd 文之路（為單頁模）
- **可選**：是否於覽器開其果

## 法

### 第一步：擇渲模

| 模 | 命 | 時 | 用時 |
|---|---|---|---|
| Fresh | `bash inst/scripts/render_quarto.sh` | ~5-7 分 | 內變、緩陳 |
| Cached | `bash inst/scripts/render_quarto.sh --cached` | ~1-2 分 | 微編、緩有效 |
| Single | 直 quarto.exe | ~30s | 迭一頁 |

得：依當境擇渲模：內變或緩陳用 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` 缺，渲或暗敗。重行附詳出察 R 碼之誤於 `.qmd` 塊。若獨某頁缺，驗其 `.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:` 以清渲

## 陷

- **陳之凍緩**：若 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 文檔之立