Is it possible to create a self-rendering Rmarkdown document?

Question

For typical R scripts the shebang syntax can be used to run the code within. With a file file.R

#!/usr/bin/env Rscript

<some R code here>

Running ./file.R will execute the code.

But can somehow the same be done with R-markdown? So that with a file named file.Rmd:

#!/usr/bin/env <some command>

<some markdown>
<some R code here>
<some markdown again>

Running ./file.Rmd would produce file.md?

Why not have a script that calls `rmarkdown::render` on the Rmd document? Otherwise I'm not sure how a file would know to knit itself — camille, Oct 23 '20 at 18:23
I cannot think of a way myself, hence the question. But having such a possibility would reduce some boilerplate working on multi-language projects - i.e. no need for separate rules about handling R-markdown files in Makefiles. — Karolis Koncevičius, Oct 23 '20 at 18:26

ekoam · Accepted Answer · 2020-10-31T08:30:48.570

You can treat an Rmd file as an Rscript. For instance, assume that your Rmd file looks like this

---
title: "Untitled"
author: "ekoam"
date: "`r Sys.Date()`"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

## R Markdown

This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.

When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:

```{r cars}
summary(cars)
```

## Including Plots

You can also embed plots, for example:

```{r pressure, echo=FALSE}
plot(pressure)
```

Note that the `echo = FALSE` parameter was added to the code chunk to prevent printing of the R code that generated the plot.

You can then prepend the following code to that Rmd file

#!/usr/bin/env Rscript

args <- commandArgs()
fname <- normalizePath(sub("--file=", "", args[grepl("--file=", args)]))
thisfile <- readLines(fname)
newfname <- paste0(tempdir(), "/", basename(fname))
writeLines(thisfile[-1:-which(thisfile == "q(\"no\")")], newfname)
rmarkdown::render(newfname, output_dir = dirname(fname))
q("no")

The trick here is q("no"). This line terminates the R session, and, thus, whatever written after it will be ignored. Such an effect also means high flexibility for coding because you can write almost any valid R code before that q("no"). The code above simply creates another temporary Rmd file with the same content as what is after q("no"). Then, we rmarkdown::render that temporary file and dump the output to the current directory.

The complete Rmd file looks like this

#!/usr/bin/env Rscript

args <- commandArgs()
fname <- normalizePath(sub("--file=", "", args[grepl("--file=", args)]))
thisfile <- readLines(fname)
newfname <- paste0(tempdir(), "/", basename(fname))
writeLines(thisfile[-1:-which(thisfile == "q(\"no\")")], newfname)
rmarkdown::render(newfname, output_dir = dirname(fname))
q("no")

---
title: "Untitled"
author: "ekoam"
date: "`r Sys.Date()`"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

## R Markdown

This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.

When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:

```{r cars}
summary(cars)
```

## Including Plots

You can also embed plots, for example:

```{r pressure, echo=FALSE}
plot(pressure)
```

Note that the `echo = FALSE` parameter was added to the code chunk to prevent printing of the R code that generated the plot.

One detail, the shebang should be `#!/usr/bin/env Rscript`, not `#!/usr/bin/env/Rscript` — Karolis Koncevičius, Oct 31 '20 at 08:26
Sorry about that. I missed that because I was testing with an absolute path to the Rscript binary. I have corrected that mistake. — ekoam, Oct 31 '20 at 08:30

score 2 · Answer 2 · answered Oct 26 '20 at 15:58

Disclaimer: I do not know much about Linux, nor do I have a Linux machine with R installed available to test my answer. Let me know if this does not work properly. If this inspires someone to write a better answer, I'll happily delete this one.

Let me approach this backwards:

To knit a document, we need to call rmarkdown::render().
To run this command from a command line, we can use RScript -e "rmarkdown::render('document.Rmd')", see e.g. here.
Probably you do not want to hardcode the path to Rscript but use a shebang like #!/usr/bin/env Rscript instead.
The problem with this approach is that it does not allow to pass arguments to Rscript.
I therefore propose to use a "wrapper" in the shebang that is responsible for calling Rscript.
With the name of the RMD file as argument, the required R code becomes rmarkdown::render(commandArgs(trailingOnly=TRUE)[1]).

Step by step:

Create the wraper (in any directory that is in your $PATH) and make it executable:
```
 touch KnitWrapper.sh
 chmod +x KnitWrapper.sh
```

Write the following to KnitWrapper.sh:

 #!/usr/bin/env bash
 Rscript -e "rmarkdown::render(commandArgs(trailingOnly=TRUE)[1])" $1

Make sure Rscript is in your $PATH. If you update R, update your $PATH accordingly.
In your RMD file, add the shebang #!/usr/bin/env KnitWrapper.sh.

Make your RMD file executable and run it:

 chmod +x yourDocument.Rmd
 ./yourDocument.Rmd

Unfortunately, the above is largely untested. Let me know if it does not work, so I can either fix or delete this answer.

Thank you for the answer, this is also a very nice approach, but I decided to go with another answer, as it doesn't depend on maintaining a separate file with instructions about rendering. — Karolis Koncevičius, Oct 31 '20 at 08:28

Is it possible to create a self-rendering Rmarkdown document?

2 Answers2