Build and deploy a pkgdown documentation site for an R package to GitHub Pages. Covers _pkgdown.yml configuration, theming, article organization, reference index customization, and deployment methods. Use when creating a documentation site for a new or existing package, customizing layout or navigation, fixing 404 errors on a deployed site, or migrating between branch-based and GitHub Actions deployment methods.
Configure and deploy a pkgdown documentation website for an R package.
usethis::use_pkgdown()
This creates _pkgdown.yml and adds pkgdown to .Rbuildignore.
Expected: _pkgdown.yml exists in the project root. .Rbuildignore contains pkgdown-related entries.
On failure: Install pkgdown with install.packages("pkgdown"). If _pkgdown.yml already exists, the function will update .Rbuildignore without overwriting the config.
_pkgdown.ymlurl: https://username.github.io/packagename/
development:
mode: release
template:
bootstrap: 5
bootswatch: flatly
navbar:
structure:
left: [intro, reference, articles, news]
right: [search, github]
components:
github:
icon: fa-github
href: https://github.com/username/packagename
reference:
- title: Core Functions
desc: Primary package functionality
contents:
- main_function
- helper_function
- title: Utilities
desc: Helper and utility functions
contents:
- starts_with("util_")
articles:
- title: Getting Started
contents:
- getting-started
- title: Advanced Usage
contents:
- advanced-features
- customization
Critical: Set development: mode: release. The default mode: auto causes 404 errors on GitHub Pages because it appends /dev/ to URLs.
Expected: _pkgdown.yml contains valid YAML with url, template, navbar, reference, and articles sections appropriate for the package.
On failure: Validate YAML syntax with an online YAML linter. Ensure all function names in reference.contents match actual exported functions.
pkgdown::build_site()
Expected: docs/ directory created with a complete site including index.html, function reference pages, and articles.
On failure: Common issues: missing pandoc (set RSTUDIO_PANDOC in .Renviron), missing vignette dependencies (install suggested packages), or broken examples (fix or wrap in \dontrun{}).
pkgdown::preview_site()
Verify navigation, function reference, articles, and search work correctly.
Expected: Site opens in the browser at localhost. All navigation links work, function reference pages render, and search returns results.
On failure: If the preview does not open, manually open docs/index.html in a browser. If pages are missing, check that devtools::document() was run before building the site.
Method A: GitHub Actions (Recommended)
See setup-github-actions-ci skill for the pkgdown workflow.
Method B: Manual Branch Deployment
# Build site
Rscript -e "pkgdown::build_site()"
# Create gh-pages branch if it doesn't exist
git checkout --orphan gh-pages
git rm -rf .
cp -r docs/* .
git add .
git commit -m "Deploy pkgdown site"
git push origin gh-pages
# Switch back to main
git checkout main
Expected: The gh-pages branch exists on the remote with the site files at the root level.
On failure: If the push is rejected, ensure you have write access to the repository. If using GitHub Actions deployment instead, skip this step and follow the setup-github-actions-ci skill.
gh-pages branch, / (root) folderExpected: Site available at https://username.github.io/packagename/ within a few minutes.
On failure: If the site returns 404, verify the Pages source matches the deployment method (branch deployment requires "Deploy from a branch"). Check that development: mode: release is set in _pkgdown.yml.
URL: https://username.github.io/packagename/, https://github.com/username/packagename
Expected: DESCRIPTION URL field contains both the pkgdown site URL and the GitHub repository URL, separated by a comma.
On failure: If R CMD check warns about invalid URLs, verify the pkgdown site is actually deployed and accessible before adding the URL.
development: mode: release is set in _pkgdown.ymldevelopment: mode: auto (the default). Change to mode: release.devtools::document() first.vignette("name") syntax in cross-references, not file paths.man/figures/logo.png and reference in _pkgdown.yml.url field in _pkgdown.yml to be set correctly.Rscript may resolve to a cross-platform wrapper instead of native R. Check with which Rscript && Rscript --version. Prefer the native R binary (e.g., /usr/local/bin/Rscript on Linux/WSL) for reliability. See Setting Up Your Environment for R path configuration.setup-github-actions-ci - automated pkgdown deployment workflowwrite-roxygen-docs - function documentation that appears on the sitewrite-vignette - articles that appear in the site navigationrelease-package-version - trigger site rebuild on releaseSearch for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer