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

Remove all generated files:

clean_site()

This removes:

• docs/ (or your output directory)
• _freeze/
• reference/ (generated function pages)
• Quarto cache files

Build Workflow

A typical build workflow:

# Clean previous build
clean_site()

# Build the site
build_site()

# Preview in browser
preview_site()

For incremental builds during development:

# Just rebuild (uses cache)
build_site()

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:

1. Quarto is installed: quarto::quarto_version()
2. Your .qmd files have valid YAML headers
3. 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