How do I produce R package vignettes in multiple formats?

Question

I use knitr and rmarkdown to write vignettes for R packages. Thanks to the magic of pandoc it is easy to turn these documents into a variety of formats. I would like to take advantage of this by offering vignettes as both HTML and PDF. There is support from rmarkdown to specify parameters for multiple output formats in the documents metadata block. For example, I might have something like this:

output:
  html_document:
    standalone: true
    smart: true
    normalize: true
    toc: true
    highlight: tango
    self-contained: true
    theme: cerulean
  pdf_document:
    toc: true
    highlight: tango
geometry: margin=2cm
documentclass: article
classoption: a4paper

From the R command-line I can use rmarkdown::render to build either one or both of the output documents without difficulties. However, when the package is build only the output format that is listed first is used. I have tried to include a Makefile that builds both by including something along the lines of

all: %.Rmd
    $(R_HOME)/bin/Rscript -e "rmarkdown::render('$*.Rmd', 'all')"

and that is successful in the sense that all output files are generated but only one of them is recognised as vignette by R. To get additional outputs included in docs/ they have to be added to .install_extras. While that ensures they are accessible via the HTML index they are listed separately from the vignettes and and I don't think they can be accessed from within R (via vignette()).

Is there a better way (or any automated way) to do this?

Answer 1

Two things:

1. you could 'include' the common content and have two source files with different headers, or,

2. if the extra vignette really doesn't show up in the index, write your own. From Writing R extensions: "At install time an HTML index for all vignettes in the package is automatically created from the \VignetteIndexEntry statements unless a file index.html exists in directory inst/doc. This index is linked from the HTML help index for the package." The vignette index entry might also be a clue to having your probably identically named vignettes be recognized as distinct.