using rmarkdown as a vignette engine

Question

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?

Answer 1

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

Answer 2

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.