I have hit a few problems trying to build a vignette that uses a number of relative paths to resources. Everything builds fine if I knit from the Rstudio button or call rmarkdown::render on the file directly, but when I use devtools::check or pkgdown::build_site, I get variously a message about missing resources or pandoc error 99.
I am pretty certain that this is due to the Rmd being built from the wrong directory - breaking the relative paths. If I change the paths though, then the echoed paths in my tutorial do not match what the user has just downloaded from my website.
Is there a recommended workflow for this? I tried using here::here in knitr::opts_chunk$set at one point, but I still get the error. An option for build_site to build vignettes from the document directory would be perfect, but I have not found such a parameter.
Vignettes are a special case of package documentation. Somebody installing your package must be able to recreate the vignettes' output. From the official manual Writing R Extensions (emphasis mine):
Package vignettes are tested by R CMD check by executing all R code chunks they contain (except those marked for non-evaluation, e.g., with option eval=FALSE for Sweave). The R working directory for all vignette tests in R CMD check is a copy of the vignette source directory. Make sure all files needed to run the R code in the vignette (data sets, …) are accessible by either placing them in the inst/doc hierarchy of the source package or by using calls to system.file(). All other files needed to re-make the vignettes (such as LaTeX style files, BibTeX input files and files for any figures not created by running the code in the vignette) must be in the vignette source directory. R CMD check will check that vignette production has succeeded by comparing modification times of output files in inst/doc with the source in vignettes.
This means all the files necessary for the vignette would need to be included in what users install. R CMD build doesn't seem to care if the files can be recreated, but R CMD check does.
If your documentation can't be recreated by users on a different machine, consider just creating a PDF yourself and putting it in the package's inst/doc directory. R will include it in the package's help guide. Of course, that means you'll be responsible for recreating them when needed.
If your package’s normal operation involves reading files/resources and you want to demo this using resources that you bundle with your package, you might take a look at how readr handled that problem:
In this case, the raw data required to perform the tutorial analyses is way to big to embed in the package, so I have decided to leave these out (the published package does not include vignettes and builds fine). I am using pkgdown to create a website where all the documentation is hosted. I use pkgdown::build_site for this and it works great. I also build PDF versions from the same Rmd files and make them available on the site.
The problem is running build_site (which does a great job of pulling everything together) but still keeping the relative paths in the final published web pages. I could build each web page separately but that would be reinventing the (pkgdown) wheel. The PDFs are each built separately and are not part of this problem.
As I work through the problem more - it looks like the relative paths might not actually be the problem. I am getting an error from build_site.
pkgdown issue #1163 discusses the pandoc error 99. Apparently the issue is with rmarkdown::html_vignette(), and the solution is to downgrade to rmarkdown 1.1.5 or updgrade to the dev version. Maybe this will also fix the problem you are having.