Skip to contents

Copies the static pkgdown website files to another local Git folder, then stages, commits and pushes the changes. Use pkgdown::build_site() before running this function in order to create the website files.

Use this function with caution since by default it – except for the paths listed in never_cleancompletely wipes the to_path directory!

Usage

deploy_pkgdown_site(
  pkg_path = ".",
  to_path = NULL,
  use_dev_build = NULL,
  clean_to_path = TRUE,
  never_clean = paths_to_keep,
  branch = NULL,
  commit_msg = paste0("auto-deploy pkgdown site for ", desc::desc_get_field(file =
    pkg_path, key = "Package")),
  quiet = FALSE
)

Arguments

pkg_path

Path to the R package of which the pkgdown website files are to be deployed.

to_path

Path to the Git (sub)folder to which the pkgdown website files are to be deployed. If NULL, the R options yay.local_pkgdown_deploy_paths and yay.default_local_pkgdown_deploy_parent_path will be respected. See section Setting to_path via R options for details.

use_dev_build

Whether or not to deploy the development build of the pkgdown website files. If NULL, the development.mode set in the pkgdown YAML configuration file from pkg_path will be respected.

clean_to_path

Whether or not to wipe to_path before deploying the new website files. Setting this to TRUE ensures there are no obsolete files left over from previous deployments.

never_clean

A character vector of paths relative to to_path which are preserved when wiping to_path (i.e. clean_to_path = TRUE). By default, this includes the following files and directories:

  • "netlify.toml"

  • "robots.txt"

  • "_headers"

  • "_redirects"

  • ".gitignore"

  • ".gitmodules"

  • ".gitsigners"

  • ".htaccess"

  • ".hvm"

  • ".well-known"

branch

The name of the Git branch to which the static website files are to be committed. A character scalar or NULL. If NULL, defaults to the currently checked out branch of the repository to_path belongs to.

commit_msg

The Git commit message used for the deployment. A character scalar.

quiet

Whether or not to suppress printing status output from internal processing.

Value

A vector of paths to the deployed files/folders, invisibly.

Details

This function is also registered as an RStudio add-in, allowing RStudio users to assign a custom shortcut to it or to invoke it from the command palette.

Setting to_path via R options

Instead of directly providing a valid to_path argument, you can also set to_path = NULL and provide

  • the desired deploy paths for each package in the R option yay.local_pkgdown_deploy_paths. The value of this option must be a named character vector whereas the names correspond to the package names and the values to the filesystem paths. As an example:

    options(yay.local_pkgdown_deploy_paths = c(some_pkg    = "/path/to/common_pkgdown_repo/some_pkg",
                                               another_pkg = "/path/to/common_pkgdown_repo/another_pkg",
                                               foo_pkg     = "/path/to/dedicated_foo_pkgdown_repo"))

  • a default parent path in the R option yay.default_local_pkgdown_deploy_parent_path that will be used as the deployment parent directory for all packages that are not explicitly listed in yay.local_pkgdown_deploy_paths. For example you could set

    options(yay.default_local_pkgdown_deploy_parent_path = "/path/to/common_pkgdown_repo")

    which would result in deploying the pkgdown website files of a hypothetical package named bar_pkg to /path/to/common_pkgdown_repo/bar_pkg.

A suitable place to define the above options is the .Rprofile file in the user's home directory.

See also

Other Git repository functions: deploy_static_site()