qrtdown

License

MIT + file LICENSE

Citation

Citing this package

Authors

  • Alejandro Hagan (author, maintainer)

Build beautiful R package documentation websites with Quarto.

Overview

qrtdown is a Quarto-based alternative to pkgdown for building R package documentation websites. It converts your roxygen2 documentation to Quarto markdown, processes articles, and builds a complete static website.

Features

  • Quarto-native: Uses Quarto’s website project type for maximum flexibility
  • Automatic reference docs: Converts .Rd files to Quarto markdown
  • Articles (not vignettes): Website-only content that won’t cause R CMD check errors
  • Conditional generation: Only builds pages for content that exists (citation, articles, changelog)
  • LLM documentation: Generate llms.txt for AI assistant context
  • Logo support: Automatically uses man/figures/logo.png in navbar
  • Diagnostic tools: Detailed sitrep to debug Quarto path issues
  • Easy deployment: GitHub Pages and Codeberg Pages support

Installation

# Install from GitHub
pak::pkg_install("usrbinr/qrtdown")

Quick Start

library(qrtdown)

# Set up qrtdown in your package
use_qrtdown()

# Build the documentation site
build_site()

# Preview the site
preview_site()

# Check your setup
qrtdown_sitrep()

Command Line Interface

qrtdown includes a CLI for terminal usage:

# Install the CLI (one-time setup)
use_qrtdown_cli()

Then use from your terminal:

qrtdown init                    # Initialize qrtdown
qrtdown build                   # Build the site
qrtdown build --preview         # Build and open in browser
qrtdown new article my-guide    # Create an article
qrtdown deploy                  # Deploy to pages branch
qrtdown --help                  # See all commands

Adding Content

Articles (Website-Only)

Articles are website content stored in vignettes/articles/. They are not R vignettes and won’t be processed by R CMD check:

# Create a new article
use_qrtdown_article("getting-started", title = "Getting Started")

This creates vignettes/articles/getting-started.qmd - a simple Quarto document without vignette engine metadata.

Citation Page

The citation page is only generated if you have a CITATION file:

# Creates inst/CITATION
usethis::use_citation()

# Then rebuild the site
build_site()

LLM Documentation

Generate a single text file with all documentation for AI assistants:

build_llm()
# Creates llms.txt with package metadata, README, function docs, articles, and changelog

Functions

Site Building

Function Description
build_site() Build complete documentation website
build_llm() Generate LLM-optimized documentation file
init_site() Initialize qrtdown configuration
clean_site() Remove generated files
preview_site() Preview site in browser

Component Building

Function Description
build_home() Build home page from README
build_reference() Build function reference from .Rd files
build_articles() Build articles from vignettes/articles/
build_news() Build changelog from NEWS.md
build_citation() Build citation page (if inst/CITATION exists)

Setup Functions

Function Description
use_qrtdown() Initialize qrtdown in a package
use_qrtdown_cli() Install the command-line interface
use_qrtdown_github_pages() Set up GitHub Pages deployment
use_qrtdown_codeberg_pages() Set up Codeberg Pages deployment
use_qrtdown_article() Create a website article
use_qrtdown_getting_started() Create the main “Get started” article
use_qrtdown_citation() Add citation information

Utilities

Function Description
rd_to_qmd() Convert .Rd file to Quarto markdown
qrtdown_sitrep() Detailed diagnostic report

Conditional Page Generation

qrtdown only generates pages for content that exists:

Page Generated if…
Reference Always (if man/ exists)
Articles vignettes/articles/ has .qmd/.Rmd/.md files
Citation inst/CITATION or CITATION.cff exists
Changelog NEWS.md exists
Get Started Main article exists in vignettes/articles/

The navbar automatically adjusts to only show links to pages that exist.

Configuration

Configuration is stored in _qrtdown.yml:

url: https://example.com/pkgname

template:
  theme: cosmo
  code_overflow: wrap

navbar:
  title: "pkgname 1.0.0"
  logo: man/figures/logo.png
  left:
    - text: "Get started"
      href: vignettes/articles/pkgname.qmd
    - text: "Reference"
      href: reference.qmd
    - text: "Articles"
      href: articles.qmd
    - text: "Citation"
      href: citation.qmd
    - text: "Changelog"
      href: NEWS.md

Deployment

These functions set up CI workflows for automatic deployment. After setup, every push to main automatically rebuilds and deploys your site.

GitHub Pages

use_qrtdown_github_pages()

Creates .github/workflows/qrtdown.yaml. After pushing, enable Pages in Settings > Pages > Source: GitHub Actions.

Codeberg Pages

use_qrtdown_codeberg_pages()

Creates .woodpecker/docs.yml. After pushing, enable Woodpecker CI and set Pages branch to pages in repository settings.

Manual Deployment

For manual control over when the site updates:

build_site()                      # Build locally
deploy_site(branch = "pages")     # Push to pages branch

README Format: GFM vs Quarto

Your package README uses GitHub Flavored Markdown (GFM) format:

---
format: gfm
---

Why GFM? CRAN requires README.md to be standard GitHub Flavored Markdown. Complex Quarto features (cross-references, callouts, tabsets) won’t render on CRAN or GitHub/Codeberg. On the website: qrtdown copies your README to index.qmd where Quarto renders it with full functionality. Any Quarto-specific syntax in your README will render correctly on your documentation site, even though it appears as raw text on GitHub/CRAN.

Best practice: Keep your README in GFM for maximum compatibility. Use full Quarto features in your vignettes/articles/ content, which is website-only.

Debugging

If you encounter issues (especially differences between CLI quarto render and build_site()), run:

qrtdown_sitrep(verbose = TRUE)

This shows: - qrtdown package status (installed vs load_all()) - Quarto binary path and version that R sees - Multiple Quarto installation detection - What content exists and what pages will be generated - Navbar preview

Comparison with pkgdown

Feature pkgdown qrtdown
Static site generation Yes Yes
Function reference Yes Yes
Articles In vignettes/ (can cause R CMD check issues) In vignettes/articles/ (ignored by R)
GitHub Pages Yes Yes
Codeberg Pages No Yes
Quarto features Limited Full
Custom themes Bootstrap Any Quarto theme
LLM documentation Yes (build_llm()) Yes (build_llm())
Conditional pages No (always generates all) Yes (only if content exists)
Multiple output formats HTML only HTML, PDF, etc.

File Structure

your-package/
├── man/
│   ├── figures/
│   │   └── logo.png          # Package logo
│   └── *.Rd                   # Function documentation
├── vignettes/
│   └── articles/              # Website articles (NOT R vignettes)
│       ├── getting-started.qmd
│       └── advanced-usage.qmd
├── inst/
│   └── CITATION               # Optional citation file
├── README.md
├── NEWS.md
├── _qrtdown.yml            # qrtdown config
├── _quarto.yml                # Generated Quarto config
└── docs/                      # Generated site output

Requirements

  • R >= 4.1.0
  • Quarto >= 1.3.0
  • roxygen2 (for generating .Rd files)

Acknowledgments

qrtdown is inspired by and builds upon ideas from:

  • pkgdown by Hadley Wickham, Jay Hesselberth, and Maëlle Salmon - the original and widely-used R package documentation generator
  • altdoc by Etienne Bacher - a multi-engine documentation generator that demonstrated Quarto’s potential for package docs

I am grateful to the authors and contributors of these packages for their foundational work in R package documentation.

License

MIT