Background
One of the great features of R Markdown is using it to create static websites. These websites can be quite simple with only a single page or more complex with multiple pages and options, such as the website for this course. Websites created with R Markdown can be viewed/hosted directly on GitHub or Netlify, or copied over to a server such as http://students.washington.edu.
Setup
For this exercise, we’ll create a simple personal website and host it on GitHub. Although you can disply a static website from any GitHub repo, we’ll use special repo with the same name as your GitHub username.
Create a repo
Create a new repo on GitHub called USERNAME.github.io where USERNAME is your actual GitHub username.
In the Description box, type (or copy/paste) “This is the development repo for my personal website”.
Make the repo Public.
Despite GitHub’s urging, DO NOT add a README, .gitignore or license file.
Click the green Create repository button when you’re finished.
Create RStudio project
The next step is to create a new project in RStudio. However, rather than base this new project on an existing repo, as we’ve done in the past, we’ll instead choose New Directory.
Scroll down the options for Project Type and select Postcards Website.
In the next Create Postcards Website window, enter your own GitHub username in the field for Directory name:
Choose the location where you’d like this new project to live.
Select the Trestles template from the drop-down menu.
When you are finished, check the box next to Open in new session and click the Create Project button.
Postcards website
You now have a very simply RStudio project with 3 files:
index.Rmd
frank.jpg
YOUR_USERNAME.Rproj (where YOUR_USERNAME is your GitHub username)
Content
The index.Rmd file contains the information to be displayed on your website. When first created, it should look like this:
The top section is a standard YAML that contains 4 fields:
title
image
links
output
Title
The title field in index.Rmd is the title of your website that will be displayed at the top. Go ahead and change this from Frank Mermosillo to something relative to you. For example, your first and last names would be good options.
Image
The image field in index.Rmd shows the name of the picture that will be displayed on your website. At present, it’s set to frank.jpg, so you should change this to be the name of a picture/photo you’d rather have displayed. A headshot is always a great choice, but you could use an avatar or any other image you’d like.
Note: whatever name/file you choose, you’ll need to move or copy that image file to the folder/directory where this project lives.
Links
The next block that begins with links contains a list of label/url pairs. These will be buttons on your website that someone could click to direct them to other information about you elsewhere. The last label/url pair is for your email address. Not all of these label/url pairs are necessary, so you can delete any of them if you’d like. You can also add more of them if you’d like evern more options for others. Go ahead and edit/delete/add any options you’d like here.
When you are finished, your YAML section should resemble something like this:
Build the site
Let’s go ahead and preview our website, which simply requires you to press the Knit button in the editor pane. When you do, RStudio will open a preview of your website in a new viewer window that should look something like this:
From here on, anytime you make a change to the content in index.Rmd you can just click the Knit button to instantly generate a preview.
Personal details
Now it’s time to edit index.Rmd so it contains information about you instead of Frank. At present there are headings and content for these sections:
You can edit any of these heading names and corresponding content to meet your personal preferences. Because this information is all written with standard Markdown, you can take advantage of any of the additional formatting options.
For example, the university and company names in the example template are enclosed with double-asterisks (**) so that they render in bold type. You could add an (un)ordered list, different heading levels, links to other URLs, equations, or additional images.
Here is an example of what your website could look like after you’ve edited the sections and content.
Set up version control
Once you have a complete draft of your website, it would be a good time to commit our local changes. Before we can do so, though, we need to place this project under version control with Git. There are 3 different ways to do this, each of which is equally effective.
In the shell, navigate via cd to the project’s directory and type git init.
At the command prompt in RStudio, type usethis::use_git().
From the main menu in RStudio,
- select
Tools > Project Options...
- click on
Git/SVN in the left column
- select
Git from the Version control system: dropdown menu
- click OK when you are finished
- you will be asked if you want to create a git repository; select Yes
- you will be asked if you want to restart RStudio; select Yes
You should now see a Git pane in RStudio several untracked files waiting to be committed.
Before we commit the files, let’s go ahead and delete the picture of Frank that was included in the project when it was created. In the File pane in RStudio check the box next to frank.jpg and then click the Delete button.
Now go ahead and commit your local changes to all of the files in the Git pane. Note, though, that we haven’t yet connected this repo to GitHub, so you can’t actually push your changes to the cloud.
Connecting to GitHub
Now that you have a draft of your website, it’s time to connect this local RStudio project to the GitHub repo we created at the beginning of this exercise. To do so, follow these steps:
- Click on the two purple boxes and a white square in the Git pane.
- In the field for
Remote Name: enter origin and in the field for Remote URL: copy/paste the URL of your GitHub repo (this should be https://github.com/USERNAME/USERNAME.github.io where USERNAME is your actual GitHub username).
When you are finished, click Add and RStudio will respond with a window showing you that your local main branch is set up to track the remote branch on GitHub, and that files you committed above have been pushed to your GitHub repo.
Note: If clicking Add instead takes you back to the *RStudio doesn not allow to click the New bracnh window and the Create button is grayed out, enter main in Branch name: field and then click Create.
Let’s verify that everything has indeed been pushed to GitHub by navigating to your repo there and refreshing the browser. You should now see several files listed there.
Viewing on GitHub
To view your website on GitHub, simply navigate over to USERNAME.github.io where USERNAME is your actual GitHub username. You should see something like this.
Other layouts
Postcards
At this point you should be all set up to make changes to your website design in RStudio and push them to GitHub when you’re finished. For example, we chose the Trestles template for our layout, but there are others available (see Sean Kross’ postcard templates). To switch to a different theme, simply change the YAML line
output:
postcards::trestles
to be something like
output:
postcards::jolla_blue