Posted   by 

R Markdown Website



Yixuan's blogs on statistcs, programming, and more. Publishing R Markdown using Jekyll. This post examines the features of R Markdown using knitr in Rstudio 0.96. This combination of tools provides an exciting improvement in. When you render, R Markdown 1. Runs the R code, embeds results and text into.md file with knitr 2. Then converts the.md file into the finished format with pandoc Set a document’s default output format in the YAML header:- output: htmldocument - # Body output value creates. At GitHub, we’re building the text editor we’ve always wanted: hackable to the core, but approachable on the first day without ever touching a config file. We can’t wait to see what you build with it.

This tutorial provides an introduction to creating websites using R, R Markdown and GitHub pages.

Updates were made on November 6, 2020 to simplify the personal website example as some extraneous pieces of information there were giving people problems. See new example website for my cats, John and Pete!

The current version was updated and presented at the R Ladies NYC Meetup on February 15, 2018.

This tutorial was originally presented at the Memorial Sloan Kettering Cancer Center Department of Epidemiology and Biostatistics R User Group meeting on January 23, 2018.

Types of websites

The main types of websites you may want to create include:

  1. Personal websites
  2. Package websites
  3. Project websites
  4. Blogs

R Markdown website basics

The minimum requirements for an R Markdown website are:

  • index.Rmd: contains the content for the website homepage
  • _site.yml: contains metadata for the website

A basic example of a _site.yml file for a website with two pages:

And a basic index.Rmd to create the Home page:

You can find an overview of R Markdown website basics here.

GitHub

This tutorial will focus on hosting websites through GitHub pages. Hosting websites on GitHub pages is free.

If you don’t have a GitHub account already, sign up for one at https://github.com/join?source=header-home with username YOUR_GH_NAME. I’ll be referring to this username, YOUR_GH_NAME, as “your GitHub username” throughout this tutorial.

There are other free sites for website hosting, and another popular choice is Netlify.

Personal websites

Let’s say that I wanted to build a website for my cats.

There are two main steps for creating a personal website that will be hosted on GitHub:

  1. GitHub setup
  2. Local setup

GitHub setup

  1. Create a GitHub repository (“repo”) named YOUR_GH_NAME.github.io, where YOUR_GH_NAME is your GitHub username.
  2. Initialize it with a README
    • For the GitHub inexperienced: this can ease the process of cloning the repo by initializing the remote repo with a master branch

Local setup

  1. Clone this remote repository to a local directory with the same name, YOUR_GH_NAME.github.io
  2. Add an R Project to this directory
  3. Create a _site.yml and index.Rmd file in your new directory

Why do I need an R Project?

The R Project is useful because RStudio will recognize your project as a website, and provide appropriate build tools.

Note: After creating the R Project and initial files, you may need to close the project and reopen it before R will recognize it as a website and show the appropriate build tools.

Create content

Edit the _site.yml file to change the metadata, layout, and theme of your website. Preview Jekyll themes here and play around with different options. Themes are easy to change even after you have added content.

For example, the _site.yml for my cats’ personal website looks like this:

Choose a default theme from https://bootswatch.com/3/ for easy implementation.

Edit and create .Rmd files that contain your website content, which will produce the html pages of your website when you knit them.

For example, the index.Rmd file for my cats’ personal website homepage looks like this:

In this example the image files are stored in a subdirectory of YOUR_GH_NAME.github.io named “files”.

Once you have your content written and the layout setup, on the Build tab in RStudio, select “Build Website”:

Markdown

Now your local directory contains all of the files needed for your website:

And here’s what the resulting website looks like, hi kitties!

Markdown

Deploy website

Basic approach:

  • Select “Upload files” from the main page of your GitHub repo:
  • And simply drag or select the files from the local repository:

Advanced approach (recommended):

  • use Git from the shell, from a Git client, or from within RStudio (another great reason to use an R Project!)
  • But this is not a Git/GitHub tutorial. If you want to learn more about Git/GitHub, which I encourage you to do, here’s a great resource to get you started: http://happygitwithr.com/

Custom domains

The default is for your site to be hosted at http://YOUR_GH_NAME.github.io, but you can add a custom domain name as well. There are two steps:

  1. In your GitHub repository YOUR_GH_NAME.github.io, go to Settings > GitHub pages. Type your domain name in the box under Custom domain and hit Save.
  1. Add a CNAME file to your GitHub repsitory YOUR_GH_NAME.github.io.

It will appear like this in your repository:

And inside the file you will simply have your domain name:

Package websites

An example from the website for my package ezfun:

Use Hadley Wickham’s great package pkgdown to easily build a website from your package that is hosted on GitHub. Details of pkgdown can be found on the pkgdown website, which was also created using pkgdown.

This assumes you already have an R package with a local directory and a GitHub repository.

From within your package directory run:

  • This will add a folder called docs to the local directory for your package

  • Upload/push these changes to the GitHub repository for your package

  • In the GitHub repository for your package go to Settings > GitHub pages. Select “master branch/docs folder” as the source and hit Save

  • The page will be added as to your personal website as YOUR_GH_NAME.github.io/repo_name

    • The Home page of the site will be pulled from the README file on your package repository
    • The Reference page of the site lists the included functions with their description
    • Each function can be clicked through to see the help page, if any
    • Would also build pages for any available vignettes

And you’re done, it’s that easy.

Project websites

You can create a website for a non-package repository as well. For example, I have a page on my website linking to the repository in which this tutorial is stored.

Local setup

From within the local directory of the project of interest:

  1. Create a _site.yml and index.Rmd file in your new directory
  2. Edit these files to create content and manage layout, as before for personal websites

GitHub setup

  • Upload/push these new files to the GitHub repository for your project

  • Enable GitHub pages for the repository by going to Settings > GitHub Pages, where you’ll select the “master branch” folder and hit Save

Blogs

R Markdown websites are simple to create and deploy, but can become cumbersome if you make frequent updates or additions to the website, as in the case of a blog. Luckily, the R package blogdown exists just for this purpose. blogdown is an R package that allows you to create static websites, which means that the deployed version of the website only consists of JavaScript, HTML, CSS, and images. Luckily the blogdown package makes it so that you don’t have to know any of those things to create a beautiful website for your blog, powered by Hugo.

For a complete resource on using the blogdown website, checkout this short blogdown book.

I don’t have a personal blog, so let’s look at the website I built to feature the events and blog of the R-Ladies NYC organization as an example.

Setup

The first three steps are similar to those from creating a basic R Markdown website:

  1. Create a GitHub repository named YOUR_GH_NAME.github.io, where YOUR_GH_NAME is your GitHub username, initialized with a README file
  2. Clone the GitHub repo to a local directory with the same name
  3. Add an R Project to the local directoroy

Next we get started with blogdown.

  1. Install blogdown and Hugo

  1. Choose a theme and find the link to the theme’s GitHub repository. In this case themes aren’t quite as easy to change as with basic R Markdown websites, so choose carefully.

  2. Within your project session, generate a new site. The option theme_example = TRUE will obtain the files for an example site that you can then customize for your needs. Below “user/repo” refers to the GitHub username and GitHub repository for your selected theme.

This will generate all of the file structure for your new blog.

After this is complete, you should quit and then reopen the project. Upon reopening, RStudio will recognize the project as a website.

Customizing the appearance

Make changes to the config.toml file (equivalent to the _site.yml from basic R Markdown websites) to change the layout and appearance of your website. The available features of the config.toml file will differ depending on your theme, and most theme examples come with a well annotated config.toml that you can use as a template.

R Markdown Website

Once you have customized your website features, click on the RStudio addin “Serve Site” to preview the site locally.

Writing a new blog post

There are several ways to create a new post for your site, but the easiest is using the RStudio addin “New Post”:

This opens a pop-up where you can enter the meta-data for a new post:

In addition to setting the Title, Author and Date of the post, you can additionally create categories, which will organize your posts in folders, and can add tags to posts, which can make them searchable within your site’s content. Be aware that the functioning of these features will vary by theme. Dates can be in the future to allow future release of a post.

Notice at the bottom that you can select whether to use a regular markdown (.md) or R markdown (.Rmd) file. .Rmd files will have to be rendered before generating html pages so it is best practice to limit their use to cases where R code is included.

A file name and slug will automatically be generated based on the other metadata. The slug is a URL friendly title of your post.

Hosting

A blogdown site is a bit more cumbersome both to build and to host on GitHub as compared to a regular R Markdown website, and as compared to what I described above.

Problem 1: Because it is a static site, upon building, the files needed to generate the site online are automatically created in a separate subdirectory called public within your local directory. However this will cause problems with GitHub hosting since the files to host need to be in the local YOUR_GH_NAME.github.io directory

My solution:

  1. Maintain separate directories for the source files (I named this directory “source”) and for the static files (the directory YOUR_GH_NAME.github.io) that will be generated on build. The “source” folder is where your R project and config.toml files will live.
  1. In your config.toml use the option publishDir = to customize blogdown to publish to the YOUR_GH_NAME.github.io folder, rather than to the default local location

Problem 2: GitHub defaults to using Jekyll with website content, and this needs to be disabled since blogdown sites are built with Hugo

To get around this, you need to include an empty file named .nojekyll in your GitHub repo YOUR_GH_NAME.github.io, prior to publishing.

Additional resources

A compiled list of the additional resources/links presented throughout this tutorial:

  • http://rmarkdown.rstudio.com/rmarkdown_websites.html: an overview of R Markdown website basics
  • http://happygitwithr.com/: an introduction to Git/GitHub
  • http://pkgdown.r-lib.org/: Hadley Wickham’s pkgdown website
  • https://bookdown.org/yihui/blogdown/: Yihui Xie’s blogdown book
  • https://themes.gohugo.io/: Hugo themes for use with your blogdown website

When I first started building my website, I decided to use Wix. It’s a great website builder that has lots of custom options – it is kind of like the PowerPoint of website editing. My one issue with Wix is that I wanted to easily embed some R code into its pages. I was already familiar with R Markdown, so being able to publish R Markdown documents directly would be ideal.

In the following post, I am going to ELI5 the entire process I go through to publish my R Markdown documents to a website. I probably went a little overboard embedding links, but I didn’t want anyone to feel lost trying to figure out what I was talking about at any given moment (what the heck is a fork on GitHub?). It took my some time to iron out the process, so I hope you find this helpful.

Lastly, I am running this on macOS. The process should be the same for non-macOS users, but installation of some of the packages may be a little different.

Jekyll, Markdown & Github

After some internet searching about how to publish my R Markdown files directly to a website, I discovered Jekyll. Jekyll will produce static sites from Markdown files and GitHub will host your Jekyll site for free. Installation of Jekyll was simple and and efficient, so I won’t cover it in detail here.

Once Jekyll was installed, I forked the Jekyll Now repository from GitHub to setup a basic website shell. Make sure to rename the repository to yourgithubusername.github.io since this will be your site’s custom URL. Now you can go to your URL and you will have a (very basic and generic) website!

R Studio

Most of you reading this probably already have R Studio installed. If you do not, install it! I’d recommend using R Studio for publishing your R Markdown documents since it allows you to create projects (like… for managing website content) and easily integrates with GitHub.

If R Studio is not already linked to your GitHub account, this will need to be setup. Once complete, create a new project using version control and link the repository you just created (yourgithubusername.github.io). Now, all files from the Jekyll Now repository will be available locally. This is where I do all of the editing for my posts, which I then push to GitHub once they are ready.

I would now open the _config.yml in your local repository and add some personalization and social media to your site. I linked Google Analytics and Disqus to my site so people like you can comment or chide me for any mistakes I made while writing this :). There are also some really cool Jekyll Themes available for free. Since I originally used Wix to develop my site (and signed up for a yearly subscription, doh!), I did not add a custom theme. Maybe once my subscription lapses, I will get around to this. For now, I link my ehenry09.github.io pages to my Wix site.

What Is R Markdown

R Markdown

Using Jekyll gets us one step closer to being able to publish R Markdown files. The missing link is converting the R Markdown files to Markdown, which in turn will allow Jekyll to publish them to your GitHub site. The best solution I found was developed by Nicole White. Her process uses knitr to convert an R Markdown file to Markdown and then integrates the files nicely into the Jekyll framework. I’ll walk through her process, but please give her all the credit.

First, in your root directory, create a new folder called _drafts. Create a new R Markdown file (your first post!) and save it in the _drafts folder. Make sure that you save the R Markdown file using standard Jekyll nomenclature, lowercase text separated by hyphens.

At the top of your new R Markdown file, delete output: html_document (or whatever output is specified) and add layout: post. If your post includes images, you will also need to add this chunk below as the first chunk in your post. Make sure to change name-of-your-post- below to whatever you saved your first post as.

Note: In order for the following code to work, you also need to have the URL (yourgithubusername.github.io) specified in the _config.yml file. Also, you do not need to change the https://ehenry09.github.io/ - this will automatically be generated from the _config.yml file.

In your R Markdown document, feel free to add whatever content you’d like. In Nichole White’s example she produced some simple plots using the publicly available cars dataset. I’d recommend testing out some images to ensure the paths are being correctly set.

R Markdown Website

Save the script below in your _drafts folder as r2jekyll.R. This is the script that will take a R Markdown file, using knitr convert it into Markdown, and then move the Markdown file to your _posts folder. The Markdown files in the _posts folder will in turn be published by Jekyll.

You will need to make the script executable. To do this, open up a terminal window. Navigate to the _drafts directory cd your-file-path/_drafts and execute the code chmod +x r2jekyll.R. Then you can run script below, again making sure you replace the name-of-your-post to your actual post name.

Check your _posts folder and you will see your first post in Markdown format.

Preview Your Post

I like to preview and tweak the formatting of my posts before pushing them to GitHub. To setup a local server and preview your post, navigate to the root directory of your website in the terminal and execute the command below.

R Markdown Embed Website

The text succeeding the successful command will direct you to the server address (usually http://127.0.0.1:4000/). You will now be able to preview your site using your internet browser.

TA-DA! That’s it - your first post is published!

BONUS SECTION: Publishing Jupyter Notebooks

Occasionally, I will work in Python using Jupyter Notebooks. Being able to publish these workbooks to a site would be just as amazing publishing my R Markdowns documents. Basically, I’d need to convert a Jupyter Notebook to Markdown. I found an elegant solution, nbconvert, developed by Thomas Kluyver to accomplish this file conversion. I use the Python package manager Anaconda (which I recommend if you do any work in Python), so installation of nbconvert was easy – simply run conda install nbconvert in your terminal. If you don’t have them installed already, you should also get TeX (link is for Mac users) and Pandoc. This file converter has a lot of features; you can read the documentation for yourself, however, I will walk through the basic the steps below.

First, add the Jupyter Notebook file you would like to publish to the _drafts folder. Make sure the file is named using standard Jekyll nomenclature, lowercase text separated by hyphens. Then, in the terminal, navigate to the drafts folder cd your-file-path/_drafts. Run the following code:

This converts your Jupyter Notebook to Markdown, which will allow Jekyll to publish it to your site. You will manually need to move the file to the _posts folder once complete (yeah… I will work on a script to automate this at some point) and then push it to GitHub.

That’s it! I hope somebody found this helpful. I did take me a while to put all the pieces together, but now the process is running like a well oiled machine.