Auto-linking • pkgdown

Within a package

pkgdown will automatically link to documentation and articles wherever it’s possible to do unambiguously. This includes:

Bare function calls, like build_site().
Calls to ?, like ?build_site or package?pkgdown.
Calls to help(), like help("pkgdown").
Calls to vignette(), like vignette("pkgdown").

Across packages

Linking to documentation in another package is straightforward. Just adapt the call in the usual way:

purrr::map(), MASS::addterm().
?purrr::map, ?MASS::addterm.
vignette("other-langs", package = "purrr"), vignette("longintro", package = "rpart")
purrr

If pkgdown can find a pkgdown site for the remote package, it will link to it; otherwise, it will link to https://rdrr.io/ for documentation and CRAN for vignettes. In order for a pkgdown site to be findable, it needs to be listed in two places:

In the URL field in the DESCRIPTION, as in dplyr:

URL: https://dplyr.tidyverse.org, https://github.com/tidyverse/dplyr

In the url field in _pkgdown.yml, as in dplyr

url: https://dplyr.tidyverse.org

When this field is defined, pkgdown generate a public facing pkgdown.yml file that provides metadata about the site:

pandoc: '2.2'
pkgdown: 1.3.0
pkgdown_sha: ~
articles:
  compatibility: compatibility.html
  dplyr: dplyr.html
  dplyr_0.8.0: future/dplyr_0.8.0.html
  dplyr_0.8.0_new_hybrid: future/dplyr_0.8.0_new_hybrid.html
  programming: programming.html
  two-table: two-table.html
  window-functions: window-functions.html
urls:
  reference: https://dplyr.tidyverse.org/reference
  article: https://dplyr.tidyverse.org/articles

Now, when you build a pkgdown site for a package that links to the dplyr documentation (e.g., dplyr::mutate()), pkgdown looks first in dplyr’s DESCRIPTION to find its website, then it looks for pkgdown.yml, and uses the metadata to generate the correct links.

To allow your package to be linked by other locally installed packages, even if your website is not reachable at build time, the following option needs to be set in _pkgdown.yml:

deploy:
  install_metadata: true

This allows locally installed packages to access package index metadata from the locally installed copy, which may be useful if your website require auth, or you build behind a firewall.