Introduction

This website is generated through Jekyll and hosted on Github Pages. I won’t go into details about how to build your Jekyll website on Github because there is a ton of excellent documentation out there and you’ll easily find many useful blog posts. The most important documentation to get you started is here:

I personally think Github + Jekyll is a great place to host your personal website - even if you are not a professional coder.

As a physician scientist working in basic cancer biology, I mainly use the R environment for my research. I have made it a habit to log important analysis with Rmarkdowns that I knit to html or pdf files for my records or to share with other researchers. Generating html or pdf files from Rmarkdowns is super easy in Rstudio - see here for documentation.

Now, if you want to post your Rmarkdown code on your Github/Jekyll website, there are some small caveats that need to be addressed to make that work smoothly. Below, are two solutions depending on whether you want to upload html files or markdowns. The following steps and description assume you generate your content locally and then upload / push it your github repository.

Option 1: Uploading a complete / allinclusive html file

When you generate html files form an Rmarkdown, the plots/images that your code produces are all rendered into that html file. So, when you upload and post that html file to your github page, you don’t need to specify any links or worry about paths to the images you want to display. The disadvantage, however, is that the html file won’t contain any front matter and, more generally, changing / formatting the finished html file is more tedious than editing a markdown (at least for html rookies like me). The fix for the front matter issue is simple: open the html file in any editor and add something like to following front matter to the file:

---
layout: post
title: Posting Rmarkdowns to your Jekyll website
---

You can now simply move the edited html file to your _posts folder and voila - you have your post. Although this works perfectly fine, it could become tedious if you post a lot and have to do it for every post (which is why I prefer Option 2).

Option 2: Uploading a markdown

The great thing about Github and Jekyll is that it automatically renders your markdowns (but not Rmarkdowns!) to html which is then displayed on your site. Going from an Rmarkdown to a regular markdown is simple enough in Rstudio. However, to be able to post this markdown on your Github/Jekyll site, the following issues need to be taken care of:

  • make sure you preserve / carry over the front matter
  • modify links / paths to image files so they work on your site

The following front matter will knit your Rmarkdown to a markdown (specifically, the github variant) and carry over your YAML header by setting preserve_yaml: true.

---
layout: post
title: Posting Rmarkdowns to your Jekyll website
output:
  md_document:
    variant: markdown_github
    preserve_yaml: true
---

When you knit your Rmarkdown to a markdown, image files generated by the script are placed into a subfolder and the markdown will contain links to those images. By default, these links won’t work on your Jekyll website - whether they are relative or absolute. Furthermore, having subfolders for each post will crowd your _posts folder. It’s more practical to store your image folder in an image folder in your main directory - especially if you want to use them elsewhere on your site. Setting the following knitr options will

  • store images generated by knitting the Rmarkdown to markdown in the images folder
  • make the links / paths to images in your markdown work on your Github/Jekyll website
knitr::opts_knit$set(base.dir = "/Users/jch/web/jchellmuth.github.io/", base.url = "/")
knitr::opts_chunk$set(fig.path = "images/")

After knitting, you should have your markdown (.md) in the _posts folder which is where I also keep the Rmarkdown (.Rmd). The images generated during that knit will be in your images folder. Feel free to check out one of my Rmarkdown-to-markdown posts where I use this very setup to publish R code, e.g.: https://raw.githubusercontent.com/jchellmuth/jchellmuth.github.io/master/news/_posts/2020-01-03-3C-arc-plot.Rmd https://raw.githubusercontent.com/jchellmuth/jchellmuth.github.io/master/news/_posts/2020-01-03-3C-arc-plot.md



Please feel free to email me with any questions, comments or suggestions and I’ll be happy to post them here. info at jchellmuth.com