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?
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.
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)) .
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.
Function browseVignettes returns an object of the same class; the print method displays it as an HTML page in a browser (using browseURL ).
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
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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With