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 github.com.

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

  3. Twitter, including the #rstats hash tag.

URL: http://pkgdown.r-lib.org, https://github.com/r-lib/pkgdown

Configuration

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

  • The site title, if different from the package name.

  • A path to a set of template, if you want to override the default page templates provided by the site.

  • A bootswatch theme name to easily tweak the overall appearance of the site.

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
  3. index.md
  4. README.md

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

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.

  • A package logo (recommended size 130 x 150 pixels) can be included in the first level one heading in the home page source file. This logo is also used to create a favicon for the site.
---
output: github_document
---

# packagename <img src="man/figures/logo.png" align="right" />
  • Badges in the home page source file (e.g. README.Rmd) are linked in the side bar under “Dev status”.

  • A link for bug reports is added if the BugReports field in DESCRIPTION contains a link. You can use [usethis::use_github_links()] to populate this field.

  • Licensing information is linked in the side bar using the package LICENSE and LICENSE.md files.

  • Citation information from a inst/CITATION file is linked in the side bar to the authors page.

  • Author ORCID identification numbers in the DESCRIPTION are linked under “Developers” using the ORCID logo (ORCID iD).

Authors@R: c(
    person("Hadley", "Wickham", , "hadley@rstudio.com", role = c("aut", "cre"), 
      comment = c(ORCID = "0000-0003-4757-117X")
    )
  • Extra markdown files (e.g., CODE_OF_CONDUCT.md) at the base directory or in .github/ are copied to docs/ and converted to HTML.

  • When including big graphics in the README, you may find it easier to use knitr::include_graphics("foo.png") combined with chunk option out.width = '100%'. This will make the graphic scale with the size of the page.

Reference

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:

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().

Articles

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:

See complete details in build_articles().

News

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

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

See more suggestions for writing news bullets in the tidyverse style guide.

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

In this case the NEWS.md 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.

See complete details in build_news().