Serve R Markdown based websites

R Markdown documents (with the filename extension .Rmd) are re-compiled using knitr or rmarkdown when necessary (source files are newer than output files), and the HTML pages will be automatically refreshed in the web browser accordingly.

Usage

jekyll(
  dir = ".",
  input = c(".", "_source", "_posts"),
  output = c(".", "_posts", "_posts"),
  script = c("Makefile", "build.R"),
  serve = TRUE,
  command = "jekyll build",
  ...
)

rmdv2(dir = ".", script = c("Makefile", "build.R"), in_session = FALSE, ...)

rmdv1(dir = ".", script = c("Makefile", "build.R"), in_session = FALSE, ...)

Arguments

dir: the root directory of the website
input: the input directories that contain R Markdown documents (the directories must be relative instead of absolute; same for output directories)
output: the output directories corresponding to input; for an input document foo.Rmd under the directory input[i], its output document foo.md (or foo.html) is generated under output[i] if the output document is older than the input document
script: a Makefile (see make), or (if Makefile not found) the name of an R script to re-build R Markdown documents, which will be executed via command line of the form Rscript build.R arg1 arg2 where build.R is the script specified by this argument, arg1 is the input filename, and arg2 is the output filename; inside the R script, you can use commandArgs(TRUE) to capture c(arg1, arg2), e.g. knitr::knit(commandArgs(TRUE)[1], commandArgs(TRUE)[2]); if this R script is not found, either, internal compiling methods will be used, which are basically knit(), knit2html(), or render()
serve: whether to serve the website; if FALSE, the R Markdown documents and the website will be compiled but not served
command: a command to build the Jekyll website; by default, it is jekyll build, and you can use alternative commands, such as bundle exec jekyll build
...: Server configurations passed to server_config().
in_session: whether to render the R Markdown documents in the current R session (TRUE) or in a separate new R session (FALSE); if the former, the argument script can be a function with two arguments, the filenames of the source document and the output document, respectively; an internal function (basically rmarkdown::render() or knitr::knit2html()) will be used if the script argument is not a function and in_session = TRUE

Details

The function jekyll() sets up a web server to serve a Jekyll-based website. A connection is established between R and the HTML pages through WebSockets so that R can notify the HTML pages to refresh themselves if any R Markdown documents have been re-compiled.

The functions rmdv1() and rmdv2() are similar to jekyll(), and the only difference is the way to compile R Markdown documents: rmdv1() uses the markdown package (a.k.a R Markdown v1) via knit2html(), and rmdv2() calls render() in the rmarkdown package (a.k.a R Markdown v2).

Note

Apparently jekyll() and rmdv1() require the knitr package, and rmdv2() requires rmarkdown. You have to install them before calling the server functions here.

All R Markdown documents are compiled in separate R sessions by default. If you have any R Markdown documents that should not be compiled as standalone documents (e.g. child documents), you can use different filename extensions, such as .Rmarkdown.

The baseurl argument does not work in jekyll(), and the base URL setting will be read from _config.yml (the baseurl field) of the website if present. You should not pass baseurl to the function jekyll() directly.

For the sake of reproducibility, you are recommended to compile each source document in a separate R session (i.e., use the default in_session = FALSE) to make sure they can compile on their own, otherwise the current workspace may affect the evaluation of the code chunks in these source documents. Sometimes it might be useful to compile a document in the current R session. For example, if reading data is time-consuming and it is not convenient to cache it (using the knitr chunk option cache = TRUE), you may read the data once, temporarily turn off the evaluation of that code chunk, and keep on working on the rest of code chunks so that data will not be read over and over again.

References

R Markdown v1: https://cran.r-project.org/package=markdown. R Markdown v2: https://rmarkdown.rstudio.com. For Jekyll, see https://jekyllrb.com. The GitHub repository https://github.com/yihui/blogdown-jekyll is an example of serving Jekyll websites with servr::jekyll().

Examples

if (interactive()) servr::rmdv1()  # serve the current dir with R Markdown v1
if (interactive()) servr::rmdv2()  # or R Markdown v2

# built-in examples
servr::serve_example("rmd", servr::rmdv1)
servr::serve_example("rmd", servr::rmdv2)