Build Options

Overview

qrtdown provides several options to control how your site is built. These affect performance, output location, and caching behavior.

Output Directory

By default, the site is built to docs/. Change it with:

output_dir: _site

Common choices:

Directory	Use case
`docs`	GitHub Pages (default)
`_site`	Quarto convention
`public`	GitLab Pages

Freeze/Cache for Faster Builds

qrtdown uses Quarto’s freeze feature to cache rendered output. This significantly speeds up rebuilds by only re-rendering files that have changed.

Freeze Options

Configure in _qrtdown.yml:

# Default: re-render only when source changes
freeze: auto

# Always use cached output (fastest, for CI)
freeze: true

# Never cache (always re-render everything)
freeze: false

How It Works

Setting	Behavior	Best for
`auto`	Re-render only changed files	Local development (default)
`true`	Always use cache, never re-render	CI/CD where you pre-render locally
`false`	Always re-render everything	Ensuring fresh output

The `_freeze/` Directory

The freeze cache is stored in _freeze/. You have two options:

Ignore it (don’t commit):

# .gitignore
_freeze/

Commit it (for faster CI):

git add _freeze/

Committing _freeze/ means CI can skip rendering and use your pre-built output.

Cleaning the Build

You can clean before building in two ways:

# Option 1: Use the clean argument (recommended)
build_site(clean = TRUE)

# Option 2: Separate calls
clean_site()
build_site()

The clean argument is useful when you want a guaranteed fresh build without stale cache issues.

clean_site() removes:

docs/ (or your output directory)
.quarto/ cache
_qrtdown-styles.css (generated font styles)
reference/ (generated function pages)

build_site() Arguments

Argument	Default	Description
`pkg`	`"."`	Path to package root
`examples`	`TRUE`	Run code examples
`lazy`	`FALSE`	Only rebuild changed files
`clean`	`FALSE`	Run `clean_site()` first
`quiet`	`FALSE`	Suppress progress messages

Build Workflow

For a clean build:

build_site(clean = TRUE)

For incremental builds during development:

# Uses cache, faster
build_site()

Previewing the Site

After building, use Quarto directly to preview:

# From R
quarto::quarto_preview()

Or from terminal:

quarto preview

The preview server watches for file changes and auto-reloads.

Troubleshooting Builds

Cache Issues

If you see stale content or rendering errors:

clean_site()
build_site()

Quarto Errors

qrtdown automatically clears the Quarto cache on render failures and retries. If errors persist, check:

Quarto is installed: quarto::quarto_version()
Your .qmd files have valid YAML headers
R code in articles runs without errors

Changes Not Appearing

Always use build_site() rather than running quarto render directly. Running Quarto directly may use stale configuration.

Complete Build Configuration

# Output directory
output_dir: docs

# Freeze/cache setting
freeze: auto

Quick Reference

Setting	Location	Default
Output directory	`output_dir`	`docs`
Freeze cache	`freeze`	`auto`