R Packages, 2nd Edition

Chapter 19. Website

At this point, we’ve discussed many ways to document your package:

• Function documentation or, more generally, help topics (see Chapter 16).

• Documentation of datasets (see “Documenting Datasets”).

• Vignettes (and articles) (see Chapter 17).

• README and NEWS (see Chapter 18).

Wouldn’t it be divine if all of that somehow got bundled up together into a beautiful website for your package? The pkgdown package is meant to provide exactly this magic, and that is the topic of this chapter.

Initiate a Site

Assuming your package has a valid structure, pkgdown should be able to make a website for it. Obviously that website will be more substantial if your package has more of the documentation elements just listed. But something reasonable should happen for any valid R package.

Tip

We hear that some folks put off “learning pkgdown,” because they think it’s going to be a lot of work. But then they eventually execute the two commands we show next and have a decent website in less than five minutes!

usethis::use_pkgdown() is a function you run once and it does the initial, minimal setup necessary to start using pkgdown:

usethis::use_pkgdown()

#> ✔ Setting active project to '/private/tmp/RtmpRf8Oqf/mypackage'
#> ✔ Adding '^_pkgdown\\.yml$', '^docs$', '^pkgdown$' to '.Rbuildignore'
#> ✔ Adding 'docs' to '.gitignore'
#> ✔ Writing '_pkgdown.yml'
#> • Edit '_pkgdown.yml'
#> ✔ Setting active project to '<no active project>'

Here’s what use_pkgdown() does:

• Creates _pkgdown.yml ...