Configuration Guide

Overview

qrtdown uses a two-file configuration system:

File	Purpose	Edit?	Git tracked?
`_qrtdown.yml`	Your configuration	Yes	Yes
`_quarto.yml`	Generated for Quarto	No	No (gitignored)

How It Works

When you run build_site():

Reads _qrtdown.yml
Scans package for content (articles, citation, etc.)
Generates _quarto.yml with discovered content
Runs quarto render

Important: Never edit _quarto.yml directly - it’s regenerated on every build.

Default Configuration

When you run use_qrtdown(), this configuration is created:

url: https://github.com/yourname/yourpackage
template:
  theme: cosmo
  code_overflow: wrap
navbar:
  title: mypackage 0.1.0
  left:
  - text: Reference
    href: reference.qmd
  - text: Articles
  - text: Changelog
    href: NEWS.md
  right:
  - icon: code-square
    href: https://github.com/yourname/yourpackage
    aria-label: Source code

Detailed Guides

For specific customization topics, see these articles:

Article	Topics Covered
Customizing Appearance	Themes, code formatting, custom CSS
Customizing Navigation	Navbar items, Articles dropdown, icons
Customizing the Home Page	Sidebar, metadata display, images
Organizing Function Reference	Grouping functions, pattern matching
Build Options	Output directory, freeze/cache, cleaning

Dynamic Content

Some content is auto-detected at build time. You don’t configure it - just create the files.

Content	Detection	Result
Articles	`vignettes/articles/*.qmd`	Dropdown menu listing all articles
Citation	`inst/CITATION` exists	“Citation” link added to navbar
Changelog	`NEWS.md` exists	“Changelog” link in navbar
Reference	`man/*.Rd` files	Function documentation page

Quick Reference

All settings available in _qrtdown.yml:

Setting	Location	Default
Repository URL	`url`	from DESCRIPTION
Theme	`template.theme`	`cosmo`
Code overflow	`template.code_overflow`	`wrap`
Freeze cache	`freeze`	`auto`
Output directory	`output_dir`	`docs`
Sidebar sections	`home.sidebar`	all 4 sections

Troubleshooting

Changes not appearing?

Run build_site() after editing _qrtdown.yml. The _quarto.yml is regenerated each time.

Site different when running `quarto render` directly?

Always use build_site() for consistent results. Running quarto render directly may use stale _quarto.yml.

Need advanced Quarto features?

If qrtdown doesn’t expose an option you need:

Request it: Open an issue
Use raw Quarto: Delete _qrtdown.yml and manage _quarto.yml directly (loses automatic version updates and content detection)