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: http://rmarkdown.rstudio.com. For Jekyll, see http://jekyllrb.com. The GitHub repository https://github.com/yihui/knitr-jekyll is an example of serving Jekyll websites with servr::jekyll().

Examples

Run this code

# NOT RUN {
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)
# }