This article describes how to set up a static website with jekyll that allows direct posting of Rmarkdown files as blog posts. Jekyll is a static site generator that can create simple sites or blogs. It takes pages input in Markdown, Textile, Liquid, HTML, and CSS, and outputs complete static HTML pages. The site/blog can be posted on GitHub pages, or as in this case hosted on a Digitalocean private web server. The purpose of this article is not to go into the details of setting up a jekyll site with a specific theme. It is more so to show you how you can use jekyll static site generator to publish your Rmarkdown scripts as blog posts.
- You need to have ruby installed on your system with the required gems (jekyll and bundler). I use Ubuntu and the steps to set up jekyll are described here.
- I use bundler to install jekyll simply because it makes the install process quite simple.
- This workflow should work regardless of whatever jekyll theme you use. I use the minimal mistakes because I like the way it looks and it has extensive configuration and customisation options. I didn’t use the standard gem-based theme install, I cloned the minimal mistakes repo and put in the root folder of my site. I had a number of changes I wanted to make, particularly in the
_includessections so this was an easier option for me.
- It is assumed R is installed on your system and you intend to use R to generate some of your blog posts. For the R code to run you will need the knitr and stringr packages installed.
In a nutshell, everything you would expect from a jekyll site runs as normal. You add a new post to your
_posts folder and name it using the standard naming convention. When it comes to writing an RMarkdown post there are a couple of changes to the workflow that are required in order to change an
*.Rmd post to an
*.md post, and how to handle graphical output. So this approach solves two problems:
- converting a post written in Rmarkdown and save it as a regular markdown file in the
- saving images generated in the Rmarkdown script to a folder location such that they will be parsed in the markdown script and appear in the post.
To achieve this I wrote an R script and saved it in the root folder of website. It performs the following steps:
- Defines a number of paths to specific parts of the website,
knitrglobal and chunk options,
- Gets the filename of the Rmarkdown file and uses this to make a corresponding filename for a regular markdown file,
- Sets the working directory to the location of the Rmarkdown file,
- Knits the file and saves the output as a result markdown file in the
- Makes a backup of the original Rmarkdown file and stores it in a backup location (in case it needs to e edited later),
- Cleans up the files and shuts down R.
So, all is required is that your Rmarkdown blog post is saved in and
_rmd folder in your website root. Save the following script in your website root and run it when you want to publish the post. Note - you shouls also add
*.Rmd to the excludes section of your
Here is the R script. It is also available in the repo.
library(knitr) library(stringr) # Define paths base_dir <- "~/Projects/website/" base_url <- "/" rmd_dir <- "_rmd/" output_dir <- paste0(base_dir, "_posts/") fig_path <- "assets/img/r_figs/" tmp_dir <- paste0(base_dir, "_rmd.bak/") opts_knit$set(base.dir = base_dir, base.url = base_url) opts_chunk$set(fig.path = fig_path) # This section used the name of the Rmd file and # maes an new target (output) .md file with the same name files <- list.files(paste0(base_dir, rmd_dir)) rmd_file <- files renamed_file <- str_replace(rmd_file, ".Rmd", ".md") output_file <- paste0(output_dir, renamed_file) # Change to the directory where the .Rmd file is located # and knit it, specifying the target .md file setwd(rmd_dir) knit(input = rmd_file, output = output_file) # Clean up the filesm but keep the original .Rmd file # as you may need this later on for editing. file.copy(rmd_file, tmp_dir) file.remove(rmd_file) setwd(base_dir) # Quit R q()