Can I use R Notebooks as R package vignettes?

Question

I know I can use Rmd to build package vignettes but want to know if it is possible to R Notebooks more specifically to make package vignettes. If so, is there anything different I need to write R Notebooks as package vignettes? I am using the latest versions of RStudio and devtools to write this package.

Answer 1

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.