11.2 Components

A pkgdown website consists of these components: the home page, function reference, articles, news, and the navigation bar. You may configure these components via a file _pkgdown.yml.

11.2.1 Home page

The home page is generated from the first existing file of the following files in your source package:

  • index.Rmd
  • README.Rmd
  • index.md
  • README.md

Other meta information about the package, such as the package license and author names, will be displayed automatically as a sidebar on the home page.

11.2.2 Function reference

The reference pages look like R’s own help pages. In fact, these pages are generated from the *.Rd files under man/. Compared to R’s own help pages, pkgdown offers a few more benefits: the examples on a help page (if they exist) will be evaluated so that you can see the output, and function names are automatically linked so you can click on a name to navigate to the help page of another function. What is more, pkgdown allows you to organize the list of all functions into groups (e.g., by topic), which can make it easier for users to find the right function in a list. By default, all functions are listed alphabetically just like R’s help system. To group functions on the list page, you need to provide a reference key in _pkgdown.yml, e.g.,

reference:
  - title: "One Topic"
    desc: "These functions are awesome..."
    contents:
      - awesome_a
      - awesome_b
      - cool_c
  - title: "Another Topic"
    desc: "These functions are boring..."
    contents:
      - starts_with("boring_")
      - ugh_oh

As you can see from the above example, you may list the names of functions in the contents field, or provide a pattern to let pkgdown match the names. There are three ways to match function names: starts_with() to match names that start with a string, ends_width() for an ending pattern, and matches() for an arbitrary regular expression.

11.2.3 Articles

Package vignettes in the R Markdown format under the vignettes/ directories will be built as “articles” for a pkgdown-based website. Note that Rmd files under subdirectories will also be built. The list of articles will be displayed as a drop-down menu in the navigation bar.

If you have a vignette that has the same base name as the package name (e.g., a vignette foo.Rmd in a package foo), it will be displayed as the “Get started” menu item in the navigation bar.

11.2.4 News

If the source package has a news file NEWS.md, it will be parsed and rendered to HTML pages that can be accessed via the “Changelog” menu in the navigation bar.