Build .md vignette using devtools

Question

I’m using knitr::rmarkdown (but knitr::knitr does the same) as my VignetteEngine. I then build my package vignette using devtools::build_vignettes().

This works, but only creates HTML and R output files in inst/doc. What I want is a Markdown output file, since only that can be displayed directly within the Github project pages (for HTML files, Github shows the source and for Rmd files it shows a rendered output but — obviously — without executing the R blocks).

I’ve tried finding out how to specify the output for custom VignetteEngines and I think that it should be possible (after all, other packages use this to build PDF vignettes, at a minimum) but I cannot find a way of doing this via devtools::build_vignettes. Is there no way around building the vignette manually (i.e. via knitr::knit or similar mechanisms that ignore the VignetteBuilder directives)?

I can’t find relevant information in the documentation/source either.

Answer 1

The only output formats for vignettes are HTML and PDF (and LaTeX, but it is converted to PDF, not displayed). Markdown isn't supported.

You can have arbitrary documentation files in your package (by convention you put them in inst/doc), but they aren't considered to be vignettes, so they won't be automatically built, functions like browseVignettes() will ignore them, etc.

To convert an Rmd file to md, just run knitr::knit on it.