jekyll: Serve R Markdown based websites

Description

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).

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

Run this code

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)