Imagine you can write books, articles, or blogs freely with simple markup formattings, and with the statistical analyses, tables and plots automatically created by R. All the gory details to shape your web site or your book, … or both simultaneously, are handled transparently in the background. Just write - save, write - save, … and enjoy the almost real-time display of the final result everytime you save your work. It would be nice, isn’t it? Brilliant minds, like Yihui Xie and Hadley Wickham did the same dream and they wrote code to make it come true. We bring these tools just a little bit further in the direction of a versatile and easy to use authoring tools for data scientists.
Figure: This blog edited in R Studio (top left) while this web site is build on every save (at right) by R (bottom left).
The new SciViews web site (as of 2015-11-17) is build on Github using Github-Pages and Jekyll, but also R Markdown and Knitr. Yihui Xie’s idea is to write posts in R Markdown (.Rmd files), and to rebuild the whole web site everytime a .Rmd page is saved. Of course, Knitr only recompiles the page that you modified, while Jekyll rebuilds the whole site according to such changes. The R package servr makes the horse work.
The SciViews Jekyll template is based on the excellent So Simple Jekyll theme, by Michael Rose, largely modified to fit with the servr approach, and to allow different categories that look either like structured documents (similar to Hadley Wickham’s book sites, like Advanced R), or as a collection of pages just sorted by dates (blog).
Once the required tools are installed (see here), authoring is very simple. In R Studio, just make the root directory of your web site the active directory in R and issue
servr::jekyll(). From this moment on, R monitors all your .Rmd files, and triggers rebuild of the web site on every change. Open your .Rmd files, edit them, save them. That’s all. Once you are happy with the result, push your data to Github. Done!
R code chunks
Of course, as your R markdown pages embed R chunks, you include computation and statistical analyses right inside your pages, like this:
## Hi from R and R markdown!
##  -0.3818247 -1.7136016 1.5182213 0.6889598 -1.9501875 -0.5586070 ##  -0.2265847 -0.5291636 -0.5930932 0.9457798
##  255 123
##  1 8 27 64 125 216 343 512 729 1000
Generate a well-formatted table with
Table: Head of the
Now, a plot:
Figure: A scatterplot of the
Of course, you can also embed R code in the text. For instance, we use R version 3.2.2 (2015-08-14) and 1 + 1 makes 2.
This is a math display:
… and some inline math (note that, in R Studio, you must use
$ ...$ for inline math, on the contrary to kramdown that also uses
$$ ... $$, as for display math blocks).
The central function:
Here is the
Place your .Rmd files in
_source subdirectory, and servr will compile them into markdown files in the
_posts subdirectory. Due to a bug in Jekyll (< v2.5.3), it is not a good idea to place both .Rmd and .md files in the same directory. From there, Jekyll just sees a usual series of .md files in
_posts, and it uses them to compile the web site. The SciViews template does the rest to ensure a modern and clear organization of your material1.
The central elements are the
build.R script and
_source/Makefile that specify how .Rmd page should be compiled (see
?servr::jekyll for more details). Knitr options can also be specified in the
There is also a built-in mechanism to save plots in a specific directory and to serve them from a specific address (e.g., by using your public dropbox folder). That way, you can keep these binary files out of your Git/Github repository, which is always a good idea.
Yihui Xie’s post explains how to set up a web site with default Jekyll template to use
servr::jekyll(). A good starting point to understand how it works in fine details.
Pandoc-style citations are not usable yet with Github-Pages. We still have to find a workaround. We also need to implement the code to compile PDF, ePub and MOBI version of books. Finally, it would be also nice to think about how to implement electronic lab notebooks with similar tools. ↩