Render Puzzle Docs

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

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

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

Cached render (uses existing _freeze files):

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

Single page (render one .qmd file directly):

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

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:

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