Watch a package and rebuild pkgdown docs when they change

pkgdown-watch.R

#!/usr/bin/env -S Rscript --vanilla

rlang::check_installed(c("docopt", "pkgdown", "servr", "fs", "pkgload"))

'usage:
  pkgdown-watch [--port=<port> --rebuild --no-sound]
  pkgdown-watch -h | --help

options:
 --port=<port> Port to use for the server [default: 4323]
 --rebuild     Rebuild the site before starting the server
 --no-sound    Disable the beep alert
 -h --help     Show this screen' -> doc

library(docopt)
opts <- docopt(doc)

library(fs)

OK_BEEP <- !isTRUE(opts[["--no-sound"]])
if (OK_BEEP) {
  rlang::check_installed("beepr")
}

pkgload::load_all()
pkg <- pkgdown::as_pkgdown(".")
docs_dir <- pkg$meta$destination
if (is.null(docs_dir)) {
  pkg$meta$destination <- docs_dir <- "docs" # default
}

if (isTRUE(opts$rebuild) || !dir.exists(docs_dir)) {
  pkgdown::build_site(pkg)
}

servr::httw(
  dir = docs_dir,
  watch = path_rel(getwd(), start =  path_abs(docs_dir)),
  pattern = "[.](Rm?d|y?ml|s[ac]ss|css|js)$",
  handler = function(files) {
    pkgload::load_all()

    files_rel <- path_rel(path_abs(path(docs_dir, files)), start =  getwd())
    cli::cli_inform("{cli::col_yellow('Updated')} {.val {files_rel}}")

    articles <- grep("vignettes.+Rmd$", files, value = TRUE)
    do_alert <- length(articles) > 0

    if (length(articles) == 1) {
      name <- path_ext_remove(path_rel(articles, path(pkg$src_path, "vignettes")))
      pkgdown::build_article(name, pkg)
    } else if (length(articles) > 1) {
      pkgdown::build_articles(pkg, preview = FALSE)
    }

    refs <- grep("man.+R(m?d)?$", files, value = TRUE)
    if (length(refs)) {
      pkgdown::build_reference(pkg, preview = FALSE, lazy = FALSE)
      do_alert <- TRUE
    }

    pkgdown <- grep("pkgdown", files, value = TRUE)
    if (length(pkgdown) && !pkgdown %in% c(articles, refs)) {
      pkgdown::init_site(pkg)
    }

    pkgdown_index <- grep("index[.]Rmd$", files_rel, value = TRUE)
    if (length(pkgdown_index)) {
      devtools::build_rmd(pkgdown_index)
      pkgdown::build_home(pkg)
    }

    readme <- grep("README[.]rmd$", files, value = TRUE, ignore.case = TRUE)
    if (length(readme)) {
      devtools::build_readme(".")
      pkgdown::build_home(pkg)
    }

    if (OK_BEEP && do_alert) beepr::beep(sound = 2)
  },
  port = opts[["port"]]
)

To use this script, download it and put it somewhere in your $PATH (what is path?). I store mine in ~/.local/bin, which I added to my path in ~/.zshrc. Change the file name to pkgdown-watch (without the .R) while you're at it.

Then make the file executable

chmod +x ~/.local/bin/pkgdown-watch

Now you can open an R package in your terminal and run pkgdown-watch in your package directory

myPkg $ pkgdown-watch

to start up a preview server of your documentation. Whenever you re-document or update an article or a static pkgdown asset, the watcher will rebuild the relevant part of your pkgdown site.