Standing on the shoulder of giants

None of this would be possible without these trailblazers and the open source community

Reproducible Research

R Markdown

Quick Start

We first start with a minimal, complete, and verifiable example (MCVE) to ensure you have all the correct dependencies and updated versions of software installed. In Rstudio, create a new R Markdown document:

Select Document and ensure that the default output format is HTML. Enter a title if you wish, but you can change this later. Click on OK:

A default skeleton of R Markdown code is included everytime you create a new R Markdown document within RStudio. The important pieces of the document are highlited in the figure below. The YAML header is very similar to the header in LaTeX; it contains all the options for the document. The two mandatory pieces in the YAML are a title and the output format. See here for further customizations.

Leave the content as is and click on the knit button:

This will prompt you to save the file:

An RStudio window of the compiled HTML file should appear

The following figure shows exactly what happens when you press the Knit button. The .Rmd file is first converted into a markdown (.md) file, which is subsequently converted by a tool called pandoc into the format specified by output: in the YAML:

Remarks

Introduction

Even until a couple of years ago, creating a website along with a blog that embeded both code and text, required specific knowledge of HTML. Tools such as markdown and R Markdown, have abstracted the difficult part of writing HTML code for us, so that we can focus on content and creating reproducible analyses. Building on these very tools, the blogdown package by Yihue Xie has made it that much easier to create websites that allow you to showcase your scripts, code and reports, while also maintaining a public portfolio, i.e., having an online presence.

In this part, we will create a minimal working example of a blogdown website. I have provided detailed screenshots with annotations of each step. In general a red encircled annotation means you should click on it, and a red rectangular annotation means that you should verify or be aware of this. Note: the screenshots provided here are from a Linux operating system, however it will be similar on a Windows or Mac.

Step 1: Create 2 git repos

We first need to create two GitHub repositories (abbreviated as repo). One will hold the source code for your website, and the other will host the compiled HTML files which make up your website (these are often referred to as static files). Head over to your GitHub account online and create a new repository:

Give it a name. It can be anything you want such as website, website_source, source (just pick a name that will remind you that this repository contains the source files of your website). In the screenshots below I used website throughout. Check the box to initialize the repository with a README and then click on Create repository:

You should now see the homepage of your repository. Note the URL for the repository is given by https://github.com/<user-name>/<repo-name>. This online version of this repo is called the remote.

Click on the Clone or download green button and copy the URL to your clipboard:

We now want a local copy of the website repo so that we can start creating content to put on our website. Head over to RStudio and go to File --> New Project..:

Select Version Control:

Then select Git:

Paste the repository URL that you copied from your remote GitHub repo. Enter a project directory name (I call it the same as the repo name), and if you want, copy the files of the remote repo to a specific subdirectory:

You will notice that a .Rproj file was created and a .gitignore file was created. Let’s first test to see if our connection from the local repo to the remote repo is working. We first check the boxes next to each file and click on commit:

Enter a commit message and click on Commit:

If everything went ok, you should see a window like this:

Next we want to Push these local changes to the remote. Click on the Push button:

This will prompt you to enter your GitHub username:

… and password:

If everything worked smoothly, you should see a window like this:

Head over to the webpage for your GitHub repo (refresh the page if necessary) and you should see you commit message, as well as a .gitignore file and a .Rproj file.

We now need to repeat the exact same steps as before to create the second repo which will host the static files for your website. Create a local copy, though it is not yet necessary to push your changes to the remote as this will be done in a later step.

Note: the name of this repo must be <user-name>.github.io.

Step 2: Install Hugo

Note for Mac Users: the first time you install Hugo, you might need to install homebrew.

library(blogdown)
blogdown::install_hugo(force=TRUE)
blogdown::hugo_version()