7  Pkgdown Websites

Recording

Create a package website using pkgdown.

Packages required for this chapter
library(usethis)  # to set up pkgdown
library(pkgdown)  # to create the pkgdown website
library(devtools) # to build the package README

# optional
library(hexSticker) # to make hex sticker
library(ggplot2)    # to make hex sticker plot
library(badger)     # to create custom badges

7.1 Set up pkgdown

The following function makes some edits to Rbuildignore (telling R to ignore these files when building the package) and .gitignore (telling git to ignore the docs directory).

run in the console
usethis::use_pkgdown()
Tip

If you already have GitHub set up with your package, use usethis::use_pkgdown_github_pages() instead. If not, we’ll cover how to link your site to GitHub in Chapter 9.

You’ll see some output that looks like this.

✔ Setting active project to '/Users/lisad/rproj/debruine/demopkg'
✔ Adding '^_pkgdown\\.yml$', '^docs$', '^pkgdown$' to '.Rbuildignore'
✔ Adding 'docs' to '.gitignore'
✔ Writing '_pkgdown.yml'
• Modify '_pkgdown.yml'

A file called _pkgdown.yml will open with the following contents.

url: ~
template:
  bootstrap: 5

While it is not required, I like to make a directory called pkgdown and keep all pkgdown-related contents in there.

run in the console
dir.create("pkgdown")
file.rename(from = "_pkgdown.yml",
            to = "pkgdown/_pkgdown.yml")

7.2 Build Site

Now check that everything is set up correctly by building the site.

run in the console
pkgdown::build_site()
Tip

If you already have GitHub set up with your package, use pkgdown::build_site_github_pages() instead.

You should see something like the following output, and then a webpage will appear in your Viewer pane or a separate window (depending on your preference settings). If you need to open it manually, open docs/index.html in a web browser.

-- Installing package into temporary library --
== Building pkgdown site ======================
Reading from: '/rproj/debruine/demopkg'
Writing to:   '/rproj/debruine/demopkg/docs'
-- Initialising site --------------------------
-- Building home ------------------------------
Reading 'LICENSE.md'
Writing '404.html'
-- Building function reference ----------------
Reading 'man/apa_t_pair.Rd'
Reading 'man/demopkg-package.Rd'
Reading 'man/self_res_att.Rd'
-- Building articles --------------------------
Reading 'vignettes/demopkg.Rmd'
Writing 'sitemap.xml'
-- Building search index ----------------------
== DONE =======================================
-- Previewing site ----------------------------

If everything is working correctly, this will have automatically organised information from the DESCRIPTION file, the README, function documentation, and vignettes into a website. If you created a vignette called demopkg, this will be available under “Get started”, and any other vignettes will be available under “Articles”. Documentation for each function will be available under “Reference”.

7.3 CITATION file

A citation file is a specially formatted file for specifying the citation to your materials. As always, you can set one up with a usethis function.

run in the console
usethis::use_citation()

This will create a file called CITATION in the directory inst (this is a directory where you can keep supplemental files your package needs). The file contains skeletons for two R functions that create the text shown when someone looks up the citation for your package. You should make this consistent with the information in the DESCRIPTION file.

If your package isn’t associated with a paper, use “Manual” instead of “Article”. Annoyingly, there is no widely accepted BibTex entry type for software, so most people just use a citation to the documentation using the manual type.

You can read and use parts of your DESCRIPTION file from the object meta. It will be available even if you don’t define it, but you can use the code below to inspect it. Unfortunately, meta$Authors needs a lot of parsing to use in the CITATION file, so it’s usually easier to just copy it, but I’ve included the parsing code below if you’re curious.

run in the console
meta <- packageDescription("demopkg")
names(meta)
 [1] "Package"                 "Date"                   
 [3] "Title"                   "Version"                
 [5] "Authors@R"               "Description"            
 [7] "License"                 "Encoding"               
 [9] "Roxygen"                 "RoxygenNote"            
[11] "Depends"                 "LazyData"               
[13] "Imports"                 "Suggests"               
[15] "Config/testthat/edition" "URL"                    
[17] "BugReports"              "NeedsCompilation"       
[19] "Packaged"                "Author"                 
[21] "Maintainer"              "Built"                  
inst/CITATION
citHeader("To cite demopkg in publications use:")

year  <- sub("-.*", "", meta$Date)
note  <- sprintf("R package version %s", meta$Version)
authors <- eval(parse(text = meta$`Authors@R`))
text_authors <- authors |>
  format(include= c("family", "given"), 
         collapse = list(family = ", ")) |> 
  paste(collapse = ", ")

bibentry(
  bibtype = "Manual",
  title = sprintf("{%s}: %s", meta$Package, meta$Title),
  author = authors,
  year = year,
  note = note,
  url = meta$URL,
  textVersion = sprintf(
    "%s, (%s). %s: %s. %s, %s",
    text_authors, year, meta$Package, meta$Title, note, meta$URL
  )
)

I prefer to use the bibentry() function instead of citEntry() because it displays the BibTex version of the citation automatically (note that it uses the argument bibtype instead of entry). The help for this function explains all of the options for citations in detail.

Save this file and re-load your package, then check the citation.

run in the console
citation("demopkg")

To cite package 'demopkg' in publications use:

  DeBruine L (2022). _demopkg: Data and analysis from DeBruine (2004)_.
  R package version 0.0.0.9000, <https://github.com/debruine/demopkg>.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {demopkg: Data and analysis from DeBruine (2004)},
    author = {Lisa DeBruine},
    year = {2022},
    note = {R package version 0.0.0.9000},
    url = {https://github.com/debruine/demopkg},
  }

Now you can build the pkgdown site again to see the citation update. However, this will run all of the vignettes, which might take a long time. You can re-build parts of the pkgdown site instead. Use auto-complete to browse the list of functions that start with build_.

run in the console
pkgdown::build_home()

7.5 Badges

You’ve probably seen these lines in the README and wondered how you can get some badges.

<!-- badges: start -->
<!-- badges: end -->

You can add a badge that describes the lifecycle of your package, from the options “experimental”, “stable”, “deprecated”, or “superceded”. Our demopkg is probably “experimental” :)

run in the console
usethis::use_lifecycle_badge("experimental")
✔ Adding Lifecycle: experimental badge to 'README.Rmd'
• Re-knit 'README.Rmd' with `devtools::build_readme()`

It will add the following text to your README.Rmd file.

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

Make sure you re-knit the README and then re-build your pkgdown home page.

Usethis has functions to add badges linking to your package on CRAN, Bioconductor, mybinder.org, or RStudio Cloud. You can also add badges that declare whether your builds are passing various checks, which we’ll discuss in Chapter 8.

The badger package lets you create the code for custom badges, which you can manually paste into the README.

run in the console
badge_doi("10.1098/rspb.2004.2824", "firebrick")

badge_custom(
  "ORCiD",
  "0000-0002-7523-5539",
  "dodgerblue",
  "https://orcid.org/0000-0002-7523-5539"
)
[1] "[![](https://img.shields.io/badge/doi-10.1098/rspb.2004.2824-firebrick.svg)](https://doi.org/10.1098/rspb.2004.2824)"
[1] "[![](https://img.shields.io/badge/ORCiD-0000--0002--7523--5539-dodgerblue.svg)](https://orcid.org/0000-0002-7523-5539)"

Make sure to add appropriate alt-text in the square brackets after the exclamation point to make your images accessible.

[![DOI:10.1098/rspb.2004.2824](https://img.shields.io/badge/doi-10.1098/rspb.2004.2824-firebrick.svg)](https://doi.org/10.1098/rspb.2004.2824)
[![ORCiD:0000-0002-7523-5539](https://img.shields.io/badge/ORCiD-0000--0002--7523--5539-dodgerblue.svg)](https://orcid.org/0000-0002-7523-5539)

7.6 Further Reading

7.7 Further Practice

  1. Customise your site using tips from this pkgdown vignette.
  2. Look through the badge types at badger and see what might be useful for you.