Package Documentation Sites with pkgdown

March 18, 2026 · 4 min read · Updated March 18, 2026 · beginner

r packages documentation pkgdown

Introduction

When you publish an R package on CRAN, users need a way to explore your functions, understand how to use them, and learn about new features. pkgdown solves this by generating a beautiful, static HTML documentation site from your package’s existing documentation files.

This guide walks you through setting up pkgdown, configuring your site, and deploying it automatically with GitHub Pages. By the end, you’ll have a professional documentation site hosted and automatically updated whenever you push changes to your package.

Installation and Initial Setup

First, install pkgdown from CRAN:

install.packages("pkgdown")
# Loading the package
library(pkgdown)

Then, initialize it in your package directory:

usethis::use_pkgdown()

This command does several important things: it creates a _pkgdown.yml configuration file in your package root, adds a GitHub Actions workflow for automated builds, and updates your package’s DESCRIPTION with the repository URL. After running this command, you’ll have a working site structure ready to build. The workflow file will handle building and deploying your site automatically whenever you push to your repository.

Building Your Site

The core function is build_site():

pkgdown::build_site()
# Building site in: docs/

This reads your package’s documentation and generates HTML files in the docs/ directory. The site includes several sections automatically, pulling content from different parts of your package. The home page is built from your README.md or index.md, the reference section is generated from all .Rd files in man/, articles are compiled from vignettes/, and the news section is rendered from NEWS.md.

You can build individual sections during development to save time. This is particularly useful when you’re working on specific parts of your documentation:

pkgdown::build_home()       # Just the home page
pkgdown::build_reference()  # Just the reference section
pkgdown::build_articles()   # Just the vignettes

Configuring Your Site

The _pkgdown.yml file controls your site’s appearance and organization. The most important setting is the URL, which enables proper linking throughout your site:

url: https://yourusername.github.io/packagename

You can customize the Bootstrap theme to match your package’s branding:

template:
  bootstrap: 5
  bootswatch: cerulean

Organize the reference section by grouping related functions together, which makes it much easier for users to find what they need:

reference:
  - title: "Data Import"
    desc: "Functions for reading data into R"
    contents:
      - read_csv
      - read_excel
      - read_fst
  - title: "Data Export"
    contents:
      - starts_with("write_")

The starts_with(), ends_with(), and matches() helper functions let you include multiple functions at once based on naming patterns.

Publishing with GitHub Pages

The easiest deployment method is GitHub Pages. Run this command once to set up automatic deployments:

usethis::use_pkgdown_github_pages()

This sets up a GitHub Actions workflow that automatically builds and deploys your site whenever you push to main. Under the hood, the workflow runs pkgdown::build_site() and pushes the output to the gh-pages branch, where GitHub Pages serves it. This means every time you push an update to your package, your documentation updates automatically.

After setup, your site will be available at https://yourusername.github.io/packagename/. Update your DESCRIPTION file to include the URL so users can find it:

URL: https://yourusername.github.io/packagename, https://github.com/yourusername/packagename

Best Practices

Keep your README focused—it’s the first thing visitors see. Include a brief description, installation instructions, and a minimal example. Save the full tutorial for a vignette, which gives you more space for detailed explanations.

For the reference section, organize functions logically rather than alphabetically. Use the desc field to explain what each group of functions does. This helps users understand the purpose of each category at a glance.

Write your NEWS.md with level-1 headings for version numbers and level-2 headings for feature categories. This creates a clean, scannable changelog that users can quickly browse:

# mypackage 1.0.0

## New Features
- Added `read_json()` function for reading JSON files
- Added support for parquet format in `write_data()`

## Bug Fixes
- Fixed error in `write_csv()` when handling NA values
- Fixed timeout issue in `download_data()`

Common Issues

If links aren’t working, make sure you’ve configured the url field in _pkgdown.yml. Without it, pkgdown generates relative links that only work when viewing the site locally but break when deployed.

Examples that fail during build_site() will stop the entire build. Use \dontrun{} for examples that require external resources, or \donttest{} for examples that take too long to run.

If your site looks wrong after an update, try running pkgdown::build_site() twice—the first build sometimes has caching issues that clear up on subsequent builds.