Introduction to pkgdown

The goal of pkgdown is to make it easy for package developers to make elegant and useful package websites. The defaults are tailored for smaller packages and for use on GitHub (using docs/ directory support), but pkgdown is flexible enough to be used as part of a bigger website. There are six parts to a pkgdown site:

  1. Home page
  2. Function reference
  3. Articles
  4. Navbar
  5. News
  6. Search

To build a pkgdown site, run pkgdown::build_site(). This will generate a complete site and open your browser for previewing.

You can configure several aspects of your site. Once your finalized site is built and published on the web, you should publicize its URL in a few places:

  1. Your repository description on

  2. The URL field of your package DESCRIPTION, alongside a link to its source:

  3. Twitter, including the #rstats hash tag.



Most pkgdown configuration options are controlled by a YAML format file named _pkgdown.yml. These options include:

Other options control the appearance of other parts of the site. See the “YAML config” sections of build_site() and the other build_ functions for complete details.

pkgdown checks for a site configuration file in these locations:

  1. _pkgdown.yml
  2. _pkgdown.yaml
  3. pkgdown/_pkgdown.yml
  4. inst/_pkgdown.yml

Including the configuration file in inst/ enables sites to be built from packages on CRAN without needing the development version of a package.

pkgdown build-ignores _pkgdown.yml with usethis::use_pkgdown(). If you use an alternative location be sure to update .Rbuildignore to avoid a NOTE during CMD CHECK.

Home page

The home page will be automatically generated from one of the following four files:

  1. index.Rmd
  2. README.Rmd

pkgdown tries them in order, which means that if you want different display for GitHub and pkgdown, you can have both and an

In addition to home page content from the README (e.g., installation instructions, simple examples), pkgdown looks for several other items to add to the home page.


pkgdown creates a function reference in reference/ that includes one page for each .Rd file in man/. This is mostly a straightforward translation of Rd to HTML. pkgdown auto-links internal and external function names to their documentation, so build_site() and dplyr::select() are linked to the pkgdown and dplyr documentation.

pkgdown includes the output of Rd @examples on each reference page including data frames and plots. Examples that are bounded by \dontrun { } are displayed in the page without their output.

pkgdown will generate a complete reference index that by default is just an alphabetically-ordered list of functions. However, the index is more useful with human curation because functions can be grouped and described in categories. To override the default, provide a reference key in _pkgdown.yml.

Use template_reference() to generate a boilerplate reference section in YAML format:

  - title: "Connecting to Spark"
    desc: >
      Functions for installing Spark components and managing
      connections to Spark
      - spark_config
      - spark_connect
      - spark_disconnect
      - spark_install
      - spark_log
  - title: "Reading and Writing Data"
    desc: "Functions for reading and writing Spark DataFrames."
      - starts_with("spark_read")
      - starts_with("spark_write")
      - matches("saveload")

The reference should be an array of objects containing title, desc (description), and list of contents. Since common prefix and suffixes are often used for functional grouping, you can use the functions starts_with() and ends_with() to automatically include all functions with a common prefix or suffix. To match more complex patterns, use matches() with a regular expression.

The objects in reference can also contain a list of targets to exclude, which allow you to exclude unwanted topics included via contents.

pkgdown will warn if you’ve forgotten to include any non-internal functions.

See complete details in build_reference().


pkgdown will automatically build all .Rmd vignettes, including those in subdirectories. The only exception are .Rmd vignettes that start with _ (i.e., _index.Rmd), enabling the use of child documents in bookdown. Vignette outputs are rendered to articles/. pkgdown will ignore the output format defined in the yaml header, and always use html_fragment(toc = TRUE, toc_float = TRUE).

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/ or add it to .Rbuildignore. In addition, you must ensure that there is no vignettes: section in the article’s 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 VignetteBuilder field.

Articles get a default index that can be customised by referring to vignette file names.

Use template_articles() to generate boilerplate articles section in YAML format:

  - title: "Extend shiny"
    desc: >
      These packages provide advanced features that can enhance your Shiny 
    - shinydashboard
    - shinythemes
    - shinyjs
    - htmlwidgets

See complete details in build_articles().


If is present, it will be rendered into a single-page Changelog based on markdown level headings. pkgdown assumes your is formatted using level one headings (#) to specify package name and version number, and level two headings (##) to provide topical organization for each release.

Use usethis::use_news_md() to create and open a template file that can be edited:

# 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.

If you have a large and want to create one page per release, you can create a multi-page change log by configuring the _pkgdown.yml:

- one_page: false

In this case the is broken up by the version specified in the level one headings. Each version will be rendered to news/, with one page per minor release, so that 2.2.0, 2.2.1, and 2.2.2 are all described on a single page.

If you want to provide detailed release notes aimed at teaching people about the new features, you can put these in e.g., vignettes/news and customise the navbar. See an example of this strategy in action for readxl.

  - text: News
    - text: "Blog posts"
    - text: "Version 1.1.0"
    - text: "------------------"
    - text: "Change log"
      href: news/index.html

See complete details in build_news().