My package has a PDF file which I'd like to include as a vignette. There are guides on the internet for doing that with Sweave and R.rsp, but I'd like to use knitr as the vignette engine because we are writing another vignette in Rmd.
My latest attempt has file.pdf and file.pdf.asis inside the vignettes/ folder, with the latter containing these two lines:
%\VignetteIndexEntry{title}
%\VignetteEngine{knitr::asis_output}
FWIW, if I use R.rsp as an engine, the second line above can simply contain %\VignetteEngine{R.rsp::asis} and that vignette builds fine, so one suspicion I have is that I am simply using the wrong knitr equivalent.
I've also tried some monstrosities involving a mix of a YAML header and LaTeX inclusion of the PDF, which didn't work either:
---
title: "title"
author: "yes"
output: pdf_document
vignette: >
%\VignetteIndexEntry{title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
\includepdf{file.pdf}
Thanks to the power of open-source software, I was able to run browseVignettes(), go through my installed packages containing a mix of HTML and PDF vignettes, and eventually check out the source code for the jsonlite package. This led me to a simple solution I thought about but immediately dismissed because I thought it wasn't possible: declare both knitr and R.rsp as vignette engines.
So my package's DESCRIPTION now includes:
VignetteBuilder: R.rsp, knitr
and I have an Rmd vignette containing %\VignetteEngine{knitr::rmarkdown} on its YAML header and a file.pdf.asis containing %\VignetteEngine{R.rsp::asis}.
Related
I'm trying to see the vignette that I've created after rebuilding a package on my local computer. Note that this has nothing to do with suggestions on this post, since I'm not cloning from Github.
The vignettes portion of my vignette file looks like this:
vignette: >
%\VignetteIndexEntry{pack_name}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
The process is:
Ctr + Shift + K to knit the vignette
Ctr + Shift + B to rebuild the package
Enter browseVignettes("package name")
Get error:
No vignettes found by browseVignettes
I also tried changing knitr::markdown to knitr::knitr, but it didn't help.
Entire vignette top-portion:
---
title: "Random title"
author: "Author"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{vignette_name}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
You don't give all the details to say what went wrong, but here is what you need to do:
Vignettes need to be in the package vignettes directory.
If they are anything but Sweave vignettes (and yours is knitr::rmarkdown, according to the header lines you showed us), then you need to tell R about it in the DESCRIPTION file. For your example, you'd need
VignetteBuilder: knitr
in that file, and also have knitr listed in the Suggests, Depends, or Imports lines.
You need to follow the naming convention for your vignette engine. For knitr::rmarkdown, name the file something.Rmd.
You don't need to knit the file yourself. R will do that when it builds the source package. (You can configure RStudio to do this for "Install and Restart"; by default it doesn't.) Even if you haven't knitted the vignette, browseVignettes should find it if you've followed the other steps properly, it just won't display the HTML or PDF output, only the source and extracted R code.
Edited to add: When building and reinstalling the package, it appears that sometimes vignettes aren't included unless the install is done from a .tar.gz file. Use the "Build Source Package" option in the RStudio build pane to get one of those.
I want to create an R package containing a latex header file which would then be available from an RMarkdown document to create a PDF with slides via TeX. When I include a reference to the latex file in the header of the RMarkdown document, I can create my slides. But I do not know how to package it. So my two related questions are:
How can I put a LaTeX-file in an R package so that it can be accessed later?
How can I include the LaTeX file in a new RMarkdown document to create slides after loading the package (like a template)?
Yes, you can. Do something like
---
output:
beamer_presentation:
includes:
in_header: my_header.tex
---
and the my_header.tex may be any (la)tex code, including package load and variable settings. You can also have before_body: and more.
If you just want packages loaded there is also a simpler way via yaml but I don't have that handy as I use the above mechanism more often.
I have been building vignettes with knitr for several months but about 10 days ago, this message appeared after using R CMD build or devtools::build():
It seems you should call rmarkdown::render() instead of knitr::knit2html() because Release.Rmd appears to be an R Markdown v2 document.
I thought it would be linked to text inside the vignette so I reduced it to a minimal reproducible example:
title: "Release"
output:
html_vignette
vignette: >
%\VignetteIndexEntry{Release}
%\VignetteEngine{knitr::knitr}
%\VignetteEncoding{UTF-8}
---
Release
Force evaluation
I tried to force the evaluation of the Rmarkdown adding:
params:
force_v1: TRUE
Change vignette builder
I also tried to replace the VignetteEngine by rmarkdown::render and editing the VignetteBuilder in the Description file. This skips the vignette building as rmarkdowndoes not seem to be a known vignette builder.
Question:
Is there a way to solve this using knitr or alternatively by building vignettes with rmarkdown?
Additional information
I tried to build the package both on Windows and Centos, with different versions. Failing build information can also be found here
I use these settings, and they work:
output: rmarkdown::html_vignette
vignette: >
%\VignetteEngine{knitr::rmarkdown}
%\VignetteIndexEntry{the title}
You should use instead
%\VignetteEngine{rmarkdown::render}
with all the packages up to date.
I am new to writing R packages. I'm trying to learn how to make a vignette for my package. I have created a vignettes folder with a file "getting-started.Rmd"
---
title: "WaterML Tutorial"
author: "Jiri Kadlec"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introduction to the WaterML R package}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
## Quick Start
This simple example shows how to get started with the <my R package>.
To build the vignette I use the command:
devtools::build_vignettes()
Then I run Rcmd.exe INSTALL my_package, and to view my vignette I run:
browseVignettes("my_package")
However I only see the vignettes in the html and source format:
As you see in the screenshot, there's no "pdf" option. How do I configure my .Rmd file to create my vignette in the pdf format?
In your header, you are telling R to output only an html vignette in line:
output: rmarkdown::html_vignette
If you want pdf, try:
output: pdf_document
According to R packages:
Output: this tells rmarkdown which output formatter to use. There are many options that are useful for regular reports (including html, pdf, slideshows, …) but rmarkdown::html_vignette has been specifically designed to work well inside packages. See ?rmarkdown::html_vignette for more details.
So you might have a few small problems using a raw pdf.
At this time, rmarkdown does not have a output: rmarkdown::pdf_vignette option
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?
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.