How to Get Rstudio to Automatically Compile R Markdown Vignettes

Can I use R Notebooks as R package vignettes?

The short answers to your two questions are yes and no, respectively.

The key to understanding R Notebooks is that they are not a different kind of file; as the documentation says:

Any R Markdown document can be used as a notebook

Since vignettes are R Markdown documents (with output: rmarkdown::html_vignette in their YAML header block), they can therefore be used as R Notebooks.

So if R Notebooks aren't a different kind of file, what are they?

Again, the documentation is succinct:

A notebook can therefore be thought of as a special execution mode for R Markdown documents

In other words, it just changes your interaction with the file. Those changes mostly have to do with making the code development process more interactive and dynamic. Perhaps most significant:

• Interactive code execution: you can execute lines or chunks as desired (compared to batch mode rendering of the entire R Markdown document)
• Embedding of code output: You can see the results of your interactive coding session displayed inside the text editing buffer of the file, and those results are updated as you run, change, and re-run code.
• Notebook files: This is a bit more complex and isn't necessarily relevant to vignettes, but bears mentioning. When you save a .Rmd file which has output: rmarkdown::html_notebook in the YAML header block, another file is created in the same directory, and which has the file extension .nb.html. This "Notebook file" stores the output of all code chunks, in whatever state you left them when you saved. It's useful for two reasons. First, when you re-open the related .Rmd file those outputs are re-loaded for you to see without needing to re-run any code (although this is also handled in a hidden way for other output types). Second, you can open these .nb.html files directly in any web browser and they'll display a rendered .html version of the notebook's state. This feature makes them useful for sharing, and the "render-as-you-go" nature saves you needing to hit knit every time you want to view an intermediate state of an unfinished notebook.

When editing in RStudio, all .Rmd documents are treated like R Notebooks (no matter what their output: field says), so you don't need to do anything and it won't affect your vignette-building process.

I'm not sure whether vignettes can take advantage of the "Notebook files" feature by adding both output: rmarkdown::html_vignette and output: rmarkdown::html_notebook to their YAML header blocks. I gave it a try but it didn't seem to work.

Compile a vignette using `devtools::build_vignette` so that .md is kept in the vignettes directory

If you are open to functions other than build_vignette(), then it is quite easy because at the end of the day, everything is just a wrapper for the external pandoc binary.

/tmp/vig> ls -l     ## start with nothing but Rmd
total 4
-rw-r--r-- 1 user grp 1015 Aug 10 14:21 soVig.Rmd
/tmp/vig> 
/tmp/vig> Rscript -e 'rmarkdown::render("soVig.Rmd", clean=FALSE)'

processing file: soVig.Rmd
  |.................................................................| 100%
   inline R code fragments

output file: soVig.knit.md

/usr/bin/pandoc +RTS -K512m -RTS soVig.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output soVig.html --smart --email-obfuscation none --self-contained --standalone --section-divs --template /usr/local/lib/R/site-library/rmarkdown/rmd/h/default.html --highlight-style pygments --css /usr/local/lib/R/site-library/rmarkdown/rmarkdown/templates/html_vignette/resources/vignette.css --mathjax --variable 'mathjax-url:https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' 

Output created: soVig.html
/tmp/vig> ls -l soVig.*
-rw-r--r-- 1 user grp 7066 Aug 10 14:24 soVig.html
-rw-r--r-- 1 user grp 1011 Aug 10 14:24 soVig.knit.md
-rw-r--r-- 1 user grp 1015 Aug 10 14:21 soVig.Rmd
-rw-r--r-- 1 user grp 1011 Aug 10 14:24 soVig.utf8.md
/tmp/vig> 

so by simply telling render() to not clean we get to keep the markdown source.

Build .md vignette using devtools

The only output formats for vignettes are HTML and PDF (and LaTeX, but it is converted to PDF, not displayed). Markdown isn't supported.

You can have arbitrary documentation files in your package (by convention you put them in inst/doc), but they aren't considered to be vignettes, so they won't be automatically built, functions like browseVignettes() will ignore them, etc.

To convert an Rmd file to md, just run knitr::knit on it.

Rmarkdown theme not applied in vignette using R CMD build

This can happen if pandoc is either not installed at system level or to old, while RStudio ships with its own version of pandoc. Therefore rendering in RStudio succeeds whereas it fails with R CMD build. Possible solutions:

• Install or update pandoc at system level
• Make the pandoc shipped with RStudio available at system level
• Build the package in RStudio (suggested by @YihuiXie)

---

Related Topics