11.2 Components

Apkgdown 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 underman/. 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 areference 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 thecontents field, or provide a pattern to letpkgdown 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, andmatches() for an arbitrary regular expression.

11.2.3 Articles

Package vignettes in the R Markdown format under thevignettes/ directories will be built as “articles” for apkgdown-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 vignettefoo.Rmd in a packagefoo), 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 fileNEWS.md, it will be parsed and rendered to HTML pages that can be accessed via the “Changelog” menu in the navigation bar.

11.2.5 Navigation bar

The navigation bar inpkgdown is based on thermarkdown site generator. You can learn how to customize it from Section10.5.4, if you are not satisfied by the default navigation bar. Please note that you need to specify thenavbar field in_pkgdown.yml instead of_site.yml.