Using rmarkdown as a vignette engine

Question

I wrote several vignettes in R Markdown with the intention of having them receive with the RStudio rmarkdown package. I know that rmarkdown::render is a function that we use to convert .rmd to.html (or any other format), however, when I put

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

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

Has anyone managed to get rmarkdown to work as a vignette?

Answer 1

Accepting @Ben's answer (and comments below), knitr registered a vignette engine that accesses rmarkdown (if installed) and

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

- An example of how we registered it. However, in order to make full use of rmarkdown (i.e. Converting .Rmd to .html and preserving any style defined in .Rmd ), you must place the code snippet above the BELOW 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 that you create your DESCRIPTION file to enable rmarkdown and knitr . The easiest way to do this is

 Suggests: knitr, rmarkdown VignetteBuilder: knitr 

Answer 2

Why do you want to use rmarkdown and not knitr ? At first glance, your question looks a little confused between rmarkdown and knitr . To clarify:

rmarkdown is an "authoring format" that is "based on knitr and pandoc." When we run rmarkdown::render , we call knitr and / or pandoc.

knitr is an engine that converts rmarkdown to html / PDF / docx. This is what R code executes to get output and graphs, etc.

The author of < knitr already mentioned that "since the rmarkdown package is not yet included in CRAN, you cannot use the knitr :: rmarkdown vignette engine at the moment." If you can’t wait, you can register your own engine , but it looks rather complicated.

I think you want:

This is at the top of your Rmd document:

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

And this is in your DESCRIPTION file:

 VignetteBuilder: knitr Suggests: knitr 

For a complete example, check out the tidyr package , here DESCRIPTION , and here rmarkdown vignette (a tip for Andrie to point this out).

If you need something specific from rmarkdown that you cannot get from knitr (user style, etc.) then you should put this in a new question.