quarto-render-and-debug

name

quarto-render-and-debug

description

Preview, render, and troubleshoot Quarto projects. Use when the user asks to "render my Quarto document", "preview my slides", "debug a rendering error", "fix a cross-reference", "my PDF won't build", "quarto render fails", "install LaTeX", "fix missing package", "deploy my Quarto project", "publish to GitHub Pages", "speed up rendering", or needs help with any Quarto CLI command, rendering issue, LaTeX error, or publishing workflow.

Quarto Rendering, Preview, and Debugging

Preview, render, and troubleshoot all Quarto project types: documents, presentations, books, and websites.

Essential Commands

Preview (Live Reload)

quarto preview                  # Auto-detects project type
quarto preview document.qmd     # Preview specific file
quarto preview --port 4321      # Custom port
quarto preview --no-browser     # Don't open browser

Preview watches for changes and auto-reloads. Use during authoring.

Render

quarto render                   # Render entire project
quarto render document.qmd      # Render single file
quarto render --to html         # Specific format
quarto render --to pdf          # PDF only
quarto render --to revealjs     # Slides only
quarto render --to docx         # Word only

Multi-Format Render

quarto render document.qmd --to html,pdf   # Both formats

Diagnostics

quarto check                    # Full installation check
quarto --version                # Show version
quarto inspect                  # Show project configuration
quarto clean                    # Remove generated files

PDF Rendering

LaTeX Engine

Quarto defaults to lualatex. Override in YAML:

format:
  pdf:
    pdf-engine: lualatex    # Default, best Unicode support
    # pdf-engine: xelatex   # Alternative with good font support
    # pdf-engine: pdflatex  # Legacy, limited Unicode

Install LaTeX

# Quarto's built-in TinyTeX (recommended)
quarto install tinytex

# macOS full distribution
brew install --cask mactex

# macOS minimal
brew install --cask basictex

# Linux
sudo apt-get install texlive-full

Missing LaTeX Packages

# Find which package provides a missing file
tlmgr search --file missing-file.sty

# Install a specific package
tlmgr install package-name

# Update all packages
tlmgr update --all

Debugging PDF Builds

# Keep intermediate LaTeX for inspection
quarto render --to pdf --keep-tex

# Verbose output
quarto render --to pdf --verbose

# Debug mode (maximum detail)
quarto render --to pdf --debug

Then examine _book/*.tex or the .tex file alongside your .qmd for LaTeX errors.

Common Errors and Fixes

Cross-References Showing "??"

Causes: Wrong label prefix, typo in reference, or missing label.

Fix:

1. Verify label uses correct prefix: #fig-, #tbl-, #eq-, #sec-, #lst-, #thm-
2. Ensure the reference uses @ syntax: @fig-label, @tbl-label
3. Check for typos — labels are case-sensitive
4. For books, ensure crossref: chapters: true in _quarto.yml
5. Try rendering twice (some cross-refs resolve on second pass)

Figures Not Displaying

Fix:

1. Verify the image file exists at the specified relative path
2. Check file extension matches exactly (case-sensitive on Linux)
3. Use relative paths from the .qmd file's location
4. For PDF: use PNG, JPG, or PDF images (SVG requires conversion)
5. Test with a simple image first to isolate the issue

"No LaTeX engine found"

quarto install tinytex

Or install a full TeX distribution (see Install LaTeX section above).

"Missing LaTeX package"

tlmgr install package-name

If you don't know the package name:

tlmgr search --file the-missing-file.sty

"Unicode character not set up for use with LaTeX"

Switch to lualatex or xelatex:

format:
  pdf:
    pdf-engine: lualatex

"Font not found"

format:
  pdf:
    mainfont: "Times"        # Use system font names
    sansfont: "Helvetica"    # macOS names differ from Windows

Or use LaTeX font packages with pdflatex:

format:
  pdf:
    fontfamily: libertinus

Citations Not Rendering

1. Verify bibliography: references.bib in YAML frontmatter
2. Check the .bib file exists at that relative path
3. Ensure citation keys in text match keys in .bib file
4. Verify BibTeX syntax in the .bib file (use a linter)

Code Execution Errors

# Check Python environment
python --version
pip list | grep jupyter

# Check R environment
R --version
R -e "installed.packages()[,'Package']"

# Force re-execution (clear cache)
quarto render --execute

For persistent issues, use freeze:

execute:
  freeze: auto    # Use cached output when source unchanged

Book/Website Won't Render

1. Validate YAML syntax: python -c "import yaml; yaml.safe_load(open('_quarto.yml'))"
2. Ensure all chapter/page files listed in _quarto.yml exist
3. Check Quarto version: quarto --version (some features require 1.4+)
4. Run quarto clean then quarto render

Revealjs Slides Not Working

1. Ensure format: revealjs (not reveal or slides)
2. Check that slide headings use ## (level 2)
3. For speaker notes, press S during presentation
4. For PDF export, append ?print-pdf to the URL in browser

Performance Optimization

Freeze Computational Output

# _quarto.yml
execute:
  freeze: auto    # Re-execute only when source changes

Commit the _freeze/ directory to version control for reproducibility.

Cache Results

execute:
  cache: true     # Cache individual code block results

Selective Rendering

# Render only changed files in a project
quarto render --changed

# Render specific files
quarto render chapter1.qmd chapter2.qmd

Publishing

Quick Deploy Commands

# GitHub Pages
quarto publish gh-pages

# Quarto Pub
quarto publish quarto-pub

# Netlify
quarto publish netlify

# Posit Connect
quarto publish connect

Manual Deploy

quarto render
# Then upload _site/ or _book/ directory to your host

Useful YAML for Debugging

# Keep all intermediate files
format:
  html:
    keep-md: true
  pdf:
    keep-tex: true
    keep-md: true

# Verbose execution
execute:
  error: true      # Show errors in output instead of failing
  warning: true    # Show all warnings
  message: true    # Show all messages

Resources

• references/error-messages.md — Comprehensive error message decoder with causes and solutions for LaTeX, cross-reference, citation, and rendering errors
• references/publishing-workflows.md — Detailed deployment guides for GitHub Pages, Netlify, Quarto Pub, Vercel, AWS S3, and CI/CD setup