How to make an RMarkdown Website

Setup:

Today, more than ever, a website is like a business card. As a graduate student or academic, by having a nice website you are not only providing a one-stop-shop for all of your necessary information, you are showing that you are savvy enough to know the importance of a high-quality web-presence, and lastly you are illustrating that you have the technical prowess to accomplish this.

Examples:

Check out Lucy’s entirely made in RMarkdown personal website!
The sample website made in this tutorial is available here.

Prerequisites:

Github account
- Don’t have one? Get one!
Working knowledge of RMarkdown.
- What is RMarkdown you ask?
Temporarily narcissistic mind-frame.

Goals:

By the end of this (hopefully) you will have,

constructed a simple website with basic information about yourself,
hosted it to github for the world to access,
have enough knowledge to know what to google to make it better.

Okay, let’s get started.

Step 1: Git on with it.

First things first, let’s set up our github repository for hosting this site.

“Hosting this site”?

Whenever you go to a website, e.g. www.Vanderbilt.edu, your computer is sending out a request across the series of tubes known as the internet to a server sitting on top of some cloud somewhere (aka Indiana) that it would like to look at Vanderbilt’s website. That server, which is simply another computer, receives the request, then goes into its hard-drive and pulls up the file it has stored for Vanderbilt.com and sends that file back to your computer. So when we say “host your site” we simply mean we need to find a server to put your website’s files on that will then deliver those sites to people who want to see them via their web browser of choice.

This all sounds very complicated and expensive, and it used to be, but now computation is so cheap that companies literally give away server space to people all the time. One example of this is github. Every time you host a repository on github it is stored on a server for access.

Create Repo

Click the plus icon in the upper right corner of your github page and select New repository.

Set up the repo how you like. In this case I am choosing “initialize repo with a README” so that I can just clone the empty repo to my computer and not bother with git initing. But this is entirely up to you. If you have github you most likely already know how to do this. If you’d like this to be your main website, name this repo yourgithubname.github.io for example, Nick’s would be nstrayer.github.io, Lucy’s would be lucymcgowan.github.io, etc.

Now select “Clone or download” and copy the link that pops up.

Now open your terminal, navigate to the area where you want to story your website on your local computer and then type in…

git clone https://github.com/nstrayer/personal_site.git  #<- Replace this with your personal link.

There are multiple ways to host websites on github. One is to create a new branch called gh-pages, the other is to tell github to manually tell github look in the master branch. We will do it the latter way.

cd personal_site/  #<- Again, replace this with your own folder name

This navigates you into your new repo.

Now we need to let github know that we want it to look for files to host in our master branch. Navigate to your repository and click Settings on the top right.

Scroll down to the Github Pages section and click the drop down menu under “Source” and click “master branch”.

Okay good! Now we have a repo setup that allows us to host websites to it. Now let’s actually get a website on it!

Start your Markdowns!

First we do some administrative work to make sure we don’t run into roadblocks on the way. Let’s update our rmarkdown package to make sure we actually have the version that supports RMarkdown websites.

install.packages("rmarkdown", type = "source")

Next we need to create a couple empty files inside your repository.

touch _site.yml #"YML" file that tells your website how to assemble itself
touch index.Rmd #Create the main rmd file
touch about.Rmd #Create an about file

Now open all of these files in RStudio.

We will start by filling out the yml file. yml files, while confusing looking at first, are basically a road-map for R to know how to assemble your website.

_site.yml

name: "nicks-website"
output_dir: "."
navbar:
  title: "Nicks Website"
  left:
    - text: "Home"
      href: index.html
    - text: "About Me"
      href: about.html

Next we will fill out the bare minimum for the .Rmd files.

index.Rmd

---
title: "Nick's Website"
---

Hello, World!

about.Rmd

---
title: "About Me"
---

Why I am awesome.

If you got lost at any point during this tutorial, you can download a template of these files from Lucy’s github.

Let’s build it!

Okay, one last step to actually have a functioning website. We need to actually turn these separate files into a single cohesive website.

To do this we are going to create one more file. This time just a plain r script.

touch build_site.R

build_site.R

#Set our working directory. 
#This helps avoid confusion if our working directory is 
#not our site because of other projects we were 
#working on at the time. 
setwd("/Users/Nick/personal_site")

#render your sweet site. 
rmarkdown::render_site()

As a note, you could skip this step if you had started by creating an RStudio project, however, by doing it this way we are not dependent upon RStudio itself. This could be helpful if in the future you are doing this on a computer without RStudio. It also helps explain the process a little bit more.

Now if everything has gone according to plan, by running the code in build_site.R you should get a bunch of unintelligible output followed by the message : Output created: index.html. If so, yay, if not, double check all the stuff above to make sure you followed it exactly. Or more likely I messed up and you should inform me.

Now we can open it up. Open the repository with finder or whatever tool your computer uses to look at files then click on index.html and hopefully you should get something that looks like this.

Sweet. You have now created your own personal website. First let’s push it to github and then we can get down to making it good for you.

Git it hosted

Now we just have to add commit and push everything to github.

#Let's add all the files to our git staging area
git add -A #the -A flag tells it git you want everything

#Now we can commit
git commit -m "My first website commit. The begining of greatness"

#Now we push. Note the addendum to normal pushing
git push origin master

Now we can navigate to our hosted site! Open your browser of choice and go to www.<your github name>.github.io/<your sites repo name>. (E.g. www.nstrayer.github.io/personal_site).

Note: github has to build stuff on its end so it may take a minute or so for stuff to show up. Just keep impatiently refreshing the page and it will go faster.

Yay, it works. Now we can make it better.

Show the world who you are.

You know how to use RMarkdown. So basically everything that you know how to do you can do here.

Like let’s say you want to make your about page more descriptive.