Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

using rmarkdown as a vignette engine

I've written a few vignettes in R Markdown, with the intention of having them get built with RStudio's rmarkdown package. I know that rmarkdown::render is the function we use to convert .rmd's to .html (or whatever other format), however, when I place

<!--
%\VignetteEnginer{rmarkdown::render}
%\VignetteIndexEntry{some test title}
-->

in the preamble of my .rmd (and knitr and rmarkdown in my Suggest's field of DESCRIPTION, as well as rmarkdown in the VignetteBuilder field) my vignette does not compile.

Has anyone managed to get rmarkdown to act as a vignette builder?

like image 267
StevieP Avatar asked Jul 21 '14 09:07

StevieP


People also ask

How do I create a vignette in R package?

To create a package vignette in R Markdown, the easiest way is through the RStudio menu File -> New File -> R Markdown -> From Template (see Figure 16.4). Then you select “Package Vignette” from the rmarkdown package, and you will get a vignette template.

How do you use vignette in R?

To see the vignette for a specific package, use the argument, browseVignettes("packagename") . Each vignette provides three things: the original source file, a readable HTML page or PDF, and a file of R code. You can read a specific vignette with vignette(x) , and see its code with edit(vignette(x)) .

What is Knitr package?

The R package knitr is a general-purpose literate programming engine, with lightweight API's designed to give users full control of the output without heavy coding work. It combines many features into one package with slight tweaks motivated from my everyday use of Sweave.

What is browseVignettes?

Function browseVignettes returns an object of the same class; the print method displays it as an HTML page in a browser (using browseURL ).


2 Answers

Taking from @Ben's answer (and the comments below), knitr has registered a vignette engine that accesses rmarkdown (if it's installed) and

<!--
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{Supplementary materials}
-->

is example of how we'd register it. However, in order to take full advantage of rmarkdown (that is, conversion of .Rmd's into .html's and preservation of any styling defined in the .Rmd) you must place the code snippet above BELOW the "rmarkdown preamble". As an example, the top of your .Rmd should look like

---
Title: "Supplementary Materials"
output:
  html_document:
    theme: flatly
---
<!--
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{Supplementary Materials}
-->

Of course, you also need to make sure you have appropriately created your DESCRIPTION file to include rmarkdown and knitr. The simplest way to do this is with

Suggests: knitr, rmarkdown
VignetteBuilder: knitr
like image 122
StevieP Avatar answered Nov 15 '22 01:11

StevieP


Why do you want to use rmarkdown rather than knitr? At first glance your question looks like a bit of confusion between rmarkdown and knitr. To clarify:

rmarkdown is an 'authoring format' that is 'based on knitr and pandoc'. When we run rmarkdown::render we are calling knitr and/or pandoc.

knitr is the engine that converts rmarkdown to html/PDF/docx. This is what is executing the R code to get output and plots and so on.

The knitr package author already mentioned that 'because the rmarkdown package is not on CRAN yet, you cannot use the vignette engine knitr::rmarkdown at the moment'. If you can't wait you could register your own engine but that looks rather complex.

I think what you want is:

This at the top of your Rmd doc:

<!--
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{Supplementary materials}
-->

And this in your DESCRIPTION file:

VignetteBuilder: knitr
Suggests:
    knitr

For a complete example, check out the tidyr package, here's the DESCRIPTION and here's the rmarkdown vignette (hat-tip to Andrie for pointing me to this).

If there's something specific you want from rmarkdown that you can't get from knitr (a custom style, etc.) then you should put that up in a new question.

like image 38
Ben Avatar answered Nov 15 '22 01:11

Ben