Render Puzzle Docs
Render jigsawR Quarto docs site.
Use When
- Build full docs site after content changes
- Render single page during iter editing
- Prep docs for release or PR
- Debug render errs in .qmd files
In
- Required: Render mode (
fresh,cached,single) - Optional: Specific .qmd path (single-page mode)
- Optional: Open result in browser?
Do
Step 1: Choose 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 |
→ Mode selected by situation: fresh for content changes/stale cache, cached for minor edits, single for iter on one page.
If err: unsure if cache stale → default fresh. Longer but guarantees correct.
Step 2: Execute
Fresh (clears _freeze + _site, re-exec all R):
cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh
Cached (uses existing _freeze):
cd /mnt/d/dev/p/jigsawR && bash inst/scripts/render_quarto.sh --cached
Single page (one .qmd direct):
QUARTO_EXE="/mnt/c/Program Files/RStudio/resources/app/bin/quarto/bin/quarto.exe"
"$QUARTO_EXE" render quarto/getting-started.qmd
→ Render completes w/o errs. Output in quarto/_site/.
If err:
- Check R code errs in .qmd chunks (look for
#| label:markers) - Verify pandoc available via
RSTUDIO_PANDOCenv var - Try clear cache:
rm -rf quarto/_freeze quarto/_site - Check all R pkgs used in .qmd installed
Step 3: Verify
ls -la /mnt/d/dev/p/jigsawR/quarto/_site/index.html
Confirm structure:
quarto/_site/index.htmlexists- Nav links resolve correctly
- Images + SVG files render properly
→ index.html exists + non-empty. Nav links resolve, images/SVGs render in browser.
If err: index.html missing → render failed silent. Re-run verbose + check R err in .qmd chunks. Only some pages missing → verify those .qmd listed in _quarto.yml.
Step 4: Preview (Optional)
Open in Windows browser:
cmd.exe /c start "" "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html"
→ Site opens in default browser for inspection.
If err: cmd.exe /c start fails from WSL → try explorer.exe "D:\\dev\\p\\jigsawR\\quarto\\_site\\index.html". Or navigate manual in browser.
Check
-
quarto/_site/index.htmlexists + non-empty - No render errs in console
- All R chunks exec OK (no err msgs)
- Nav between pages works
- All .qmd have
#| label:on chunks for clean output
Traps
- Stale freeze cache: R code changed → fresh render to regen
_freeze - Missing R pkgs: .qmd may use pkgs not in renv → install first
- Pandoc not found: Ensure
RSTUDIO_PANDOCset in.Renviron - Long renders: Fresh = 5-7 min (14 pages w/ R exec) → cached during iter
- Code chunk labels: All R chunks should have
#| label:for clean render
→
generate-puzzle— generate puzzle output ref'd in docsrun-puzzle-tests— ensure code examples correctcreate-quarto-report— general Quarto doc creation