Compile a vignette using `devtools::build_vignette` so that .md is kept in the vignettes directory

Question

I am trying to compile a package vignette such that an .md file remains in the vignette folder so that it is still visible on github. I am using devtools for all of this. I have looked at this approach and will outline it below:

I have auto-generated a vignette template use devtools::use_vignette(). Then I have modified the .Rmd file to look like this (truncated template version):

---
  title: "package"
author: "author"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
  toc: true
  keep_md: true
vignette: >
  %\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---

  Vignettes are long form documentation commonly included in packages. Because they are part of the distribution of the package, they need to be as compact as possible. The `html_vignette` output type provides a custom style sheet (and tweaks some options) to ensure that the resulting html is as small as possible. The `html_vignette` format:

  - Never uses retina figures
- Has a smaller default figure size
- Uses a custom CSS stylesheet instead of the default Twitter Bootstrap style

## Vignette Info

Note the various macros within the `vignette` section of the metadata block above. These are required in order to instruct R how to build the vignette. Note that you should change the `title` field and the `\VignetteIndexEntry` to match the title of your vignette.

So the .yaml is modified but when I compile using devtools::build_vignettes() it does not seem to leave a .md file in the vignettes directory. No error message and the vignette builds fine so this is a little confusing.

So to summarize the question, do anyone know how to compile a vignette using devtools::build_vignette such that the basic markdown file is kept in the vignettes directory?

Klondike

Have a look here... – Typist

Answer 1

If you are open to functions other than build_vignette(), then it is quite easy because at the end of the day, everything is just a wrapper for the external pandoc binary.

/tmp/vig> ls -l     ## start with nothing but Rmd
total 4
-rw-r--r-- 1 user grp 1015 Aug 10 14:21 soVig.Rmd
/tmp/vig> 
/tmp/vig> Rscript -e 'rmarkdown::render("soVig.Rmd", clean=FALSE)'


processing file: soVig.Rmd
  |.................................................................| 100%
   inline R code fragments


output file: soVig.knit.md

/usr/bin/pandoc +RTS -K512m -RTS soVig.utf8.md --to html --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output soVig.html --smart --email-obfuscation none --self-contained --standalone --section-divs --template /usr/local/lib/R/site-library/rmarkdown/rmd/h/default.html --highlight-style pygments --css /usr/local/lib/R/site-library/rmarkdown/rmarkdown/templates/html_vignette/resources/vignette.css --mathjax --variable 'mathjax-url:https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML' 

Output created: soVig.html
/tmp/vig> ls -l soVig.*
-rw-r--r-- 1 user grp 7066 Aug 10 14:24 soVig.html
-rw-r--r-- 1 user grp 1011 Aug 10 14:24 soVig.knit.md
-rw-r--r-- 1 user grp 1015 Aug 10 14:21 soVig.Rmd
-rw-r--r-- 1 user grp 1011 Aug 10 14:24 soVig.utf8.md
/tmp/vig> 

so by simply telling render() to not clean we get to keep the markdown source.

Bircher

I'd sorted of like to stay in devtools. Ultimately this is for a package that is currently only hosted in github (but will CRAN intended) so I would add the .md to.RBuildIgnore but keep it present in the repo so that I can point to it as long form documentation. – Klondike

Up to you. Last I checked, I wasn't yet outlawed to combine several different packages and base R. – Bircher

Sorry, I should have been specific. I just meant that staying in devtools meant that hopefully I wasn't left will all the other cruft from render (.knit.md. utf8.md, ,html) – Klondike

Yes, sure, one call each to file.rename() and file.remove() is clearly too difficult. – Bircher

Actually I had not thought of that. Good idea. So something like this? render_keep_md = function(vignette_name){ rmarkdown::render(paste0("./vignettes/",vignette_name, ".Rmd"), clean=FALSE) files_to_remove = paste0("./vignettes/",vignette_name,c(".html",".knit.md",".utf8.md")) lapply(files_to_remove, file.remove) } – Klondike

Yep. You need to keep one of the two .md files though, and maybe rename it. – Bircher

Sorry Dirk - why do I need to keep it? A .md is already produced. – Klondike

In the ls -l out I show above we have one input, one final output, and by setting clean=FALSE to interim files. If you remove both you are undoing the work. What am I (or you) missing here? – Bircher

Nope I understand now. Learned something today. Thanks! – Klondike

My pleasure. If the answer suits, feel free to grace it with an upvote. – Bircher

It does - I am going to see if someone more directly answer the exact question before accepting your answer. – Klondike

I think Dirk's got the solution here. I had a similar problem, with the caveat that I desired outputs in both .html and .pdf as well. After wasting much time on the build_vignette() function, the rmarkdown::render("vignettes/soVig.Rmd", output_format = "all", clean=FALSE) ultimately did what I needed. Of all approaches I considered, the render() function provided the most control over the process. – Octagonal

One suggestion is to create a separate .R file for using render() along with the functions to remove and rename files. Then .RBuildIgnore that file. The script will come in handy for future packages with similar vignette requirements. – Octagonal

Yes, I keep similar buildVignettes.r helpers (shebang'ed for either littler or Rscript) in some vignettes/ directories. A little hard to generalize, but the key is in fact the use of rmarkdown::render(). – Bircher