The goal of pkgdown is to make it easy to make an elegant and useful package website with a minimum of work. You can get a basic website up and running in just a couple of minutes:
# Run once to configure package to use pkgdown usethis::use_pkgdown() # Run to build the website pkgdown::build_site()
If you're using GitHub, we also recommend setting up GitHub actions to automatically build and publish your site:
While you'll get a decent website without any additional work, if you want a website that really pops, you'll need to read the rest of this vignette.
It starts by showing you how to configure pkgdown with a
You'll learn about the main components of the site (the home page, reference, articles, and news), and then how to publish and promote your site.
You can override pkgdown's defaults with a YAML file called
The most important field is
url, which gives the final location of the site:
[^1]: You can also put it in
pkgdown/_pkgdown.yml if you want to keep the package root clutter-free, or in
inst/_pkgdown.yml if you want to make it available when your package is installed.
url is used throughout the site to generate absolute urls where they are needed.
Another important option is
template, which allows you to control the overall appearance of your site:
template: bootstrap: 5 bootswatch: cerulean
You can learn more about controlling the appearance of your site in
If your documentation (
.Rmd) is written in a language other than English, declare it by setting setting
lang to the two letter language code for your language:
This will be used to set the language of the web page and to translate the English words that pkgdown generates on your site. Current available translations are:
zh_CN: Chinese (simplified)
The contents of home page are automatically generated from
pkgdown tries them in order, so it's possible to have a different display on GitHub and pkgdown by providing both files.
The homepage also includes a sidebar full of useful links; see
?build_home for how these are generated and how you can customise them.
pkgdown creates a function reference in
reference/ that includes one page for each
.Rd help topic in
The translation of individual help topics from Rd to HTML is generally straightforward, but there are a couple of things you should bear in mind:
pkgdown does its best to autolink all references to help topics and articles described in
pkgdown executes all examples, inserting the rendered results in the generated HTML files.
By default, pkgdown generates a reference index that is just an alphabetically-ordered list of functions.
The index is much more useful with human curation because functions can be grouped and described in categories.
To override the default, provide a
reference field in
Each entry in
reference can take one of three forms:
reference: - title: "Connecting to Spark" desc: > Functions for installing Spark components and managing connections to Spark contents: - spark_config - spark_connect - spark_disconnect - spark_install - spark_log - title: "Reading and Writing Data" desc: "Functions for reading and writing Spark DataFrames." contents: - starts_with("spark_read") - starts_with("spark_write") - matches("saveload")
Note the use of
starts_with() to select all functions with a common prefix.
You can also use
See complete details in
While iterating on the reference index you might want to run
It just re-builds the index page, making it faster to quickly change
_pkgdown.yaml and see how it affects your site.
pkgdown will automatically build all vignettes found in
vignettes/, translating them to HTML files in
Due to the way that pkgdown has to integrate RMarkdown generated HTML with its own HTML, relatively little control is available over the output format.
You can see the details in
If you want to include an article on the website but not in the package (e.g., because it's large), you can either place it in a subdirectory of
vignettes/web_only) or add it to
.Rbuildignore (and make sure that there's no
vignettes: section in the yaml header).
In the extreme case where you want to produce only articles but not vignettes, you should add the complete
vignettes/ directory to
.Rbuildignore and ensure that DESCRIPTION does not have a
NEWS.md is present, it will be rendered into a single-page changelog based on markdown level headings.
pkgdown assumes your
NEWS.md is formatted using level one headings (
#) to specify package name and version number, and level two headings (
##) to provide topical organization for each release.
# pkgdown 1.1.0 ## Bug Fixes * Lots of them # pkgdown 1.0.0 * This is the first release of pkgdown.
See more suggestions for writing news bullets in the tidyverse style guide.
?build_news for more customisation options including how to:
If you use GitHub, there are two ways to publish your site on GitHub Pages:
Build the site locally, check in the docs directory, then configure GitHub Pages to use that directory.
Use GitHub actions to automatically build and publish the site every time you make a change.
The easiest way to set this up is to run
Once your finalized site is built and published on the web, you should publicize its URL in a few places:
URL field of your package
DESCRIPTION, alongside a link to its source:
URL: https://pkgdown.r-lib.org, https://github.com/r-lib/pkgdown
usethis::use_pkgdown_github_pages() does this for you.)
Your repository description on GitHub.
On Twitter (make sure to include
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.