# Render Puzzle Docs

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

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

---


# Render Puzzle Docs

Render jigsawR Quarto documentation site.

## When Use

- Build full documentation site after content changes
- Render single page during iterative editing
- Prepare documentation for release or PR
- Debug render errors in Quarto .qmd files

## Inputs

- **Required**: Render mode (`fresh`, `cached`, or `single`)
- **Optional**: Specific .qmd file path (for single-page mode)
- **Optional**: Whether to open result in browser

## Steps

### Step 1: Choose Render Mode

| 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 |

**Got:** Render mode selected based on current situation: fresh for content changes or stale cache, cached for minor edits, single for iterating on one page.

**If fail:** Unsure whether cache is stale? Default to fresh render. Takes longer but guarantees correct output.

### Step 2: Execute Render

**Fresh render** (clears `_freeze` and `_site`, re-executes all R code):

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

**Cached render** (uses existing `_freeze` files):

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

**Single page** (render one .qmd file directly):

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

**Got:** Render completes without errors. Output in `quarto/_site/`.

**If fail:**
- Check for R code errors in .qmd chunks (look for `#| label:` markers)
- Verify pandoc available via `RSTUDIO_PANDOC` env var
- Try clear cache: `rm -rf quarto/_freeze quarto/_site`
- Check that all R packages used in .qmd files are installed

### Step 3: Verify Output

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

Confirm site structure:
- `quarto/_site/index.html` exists
- Navigation links resolve correctly
- Images and SVG files render properly

**Got:** `index.html` exists and non-empty. Navigation links resolve. Images/SVGs render correctly in browser.

**If fail:** `index.html` missing? Render likely failed silently. Re-run with verbose output. Check for R code errors in `.qmd` chunks. Only some pages missing? Verify those `.qmd` files listed in `_quarto.yml`.

### Step 4: Preview (Optional)

Open in Windows browser:

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

**Got:** Documentation site opens in Windows default browser for visual inspection.

**If fail:** `cmd.exe /c start` command fails from WSL? Try `explorer.exe "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html"` instead. Or navigate to file manually in browser.

## Checks

- [ ] `quarto/_site/index.html` exists and non-empty
- [ ] No render errors in console output
- [ ] All R code chunks executed successfully (check for error messages)
- [ ] Navigation between pages works
- [ ] All .qmd files have `#| label:` on code chunks for clean output

## Pitfalls

- **Stale freeze cache**: R code changed? Use fresh render to regenerate `_freeze` files
- **Missing R packages**: Quarto .qmd files may use packages not in renv; install them first
- **Pandoc not found**: Ensure `RSTUDIO_PANDOC` set in `.Renviron`
- **Long render times**: Fresh render takes 5-7 minutes (14 pages with R execution); use cached mode during iteration
- **Code chunk labels**: All R code chunks should have `#| label:` for clean rendering

## See Also

- `generate-puzzle` — generate puzzle output referenced in documentation
- `run-puzzle-tests` — ensure code examples in docs are correct
- `create-quarto-report` — general Quarto document creation