Chapter 12 Communication: OHI+ websites

In development.

The purpose of Chapter 12 is for you to communicate the technical work you do to wider audiences. This is a a 1-hour hands-on training: you will be following along on your own computer and working with a copy of the demonstration repository that is used throughout the this chapter.

12.1 Overview

Your GitHub repository has a free accompanying website that you can use to communicate your work to the audiences you need to reach. You can modify and use this website from the very beginning to identify team members, share workshop agendas, and increasingly, to share the technical decisions underlying your OHI+ assessment, the data, the scores, and what it means.

This chapter will teach you how to modify your OHI+ website. These websites are created using RStudio’s R Markdown and hosted on Github. This is a really powerful way to communicate science using the same reproducible workflow you already use for your analyses and collaborations, in this case with OHI. Importantly, creating websites with R Markdown can be done without knowing R or any web-design languages (HTML, CSS, etc), and that’s where we’ll start. However, R Markdown integrates with these tools so the more you know the more complex and beautiful your website can be.

This tutorial borrows heavily from Making free websites with RStudio’s R Markdown, but has been augmented to include OHI-specific information.

12.1.1 Prerequisites

Before the training, please make sure you have done the following:

  1. Have up-to-date versions of R and RStudio and have RStudio configured with Git/GitHub
  2. Fork the toolbox-demo repository into your own GitHub account by going to https://github.com/OHI-Science/toolbox-demo, clicking “Fork” in the upper right corner, and selecting your account
  3. Clone the toolbox-demo repo from your GitHub account into RStudio into a folder called “github” in your home directory (filepath “~/github”)
  4. Get comfortable: be set up with two screens if possible. You will be following along in RStudio on your own computer while also watching an instructor’s screen or following this tutorial.

Additionally, this chapter assumes you are familiar with content from Chapter 8, so review that first if needed.

12.2 First Observations

We will start with a working example website that we will explore together to understand the website architecture. We’ll learn a few rules and look for patterns to get an understanding of what things do.

Then we’ll get it onto to our local computers. Locally, we will explore further by going back and forth between the R Markdown editor and built webpages, and make modifications. Pushing to Github will make our modifications live!

12.2.1 Exploring Online

Let’s start by looking at the toolbox-demo website, which lives at ohi-science.org/toolbox-demo.

12.2.1.1 The website itself

This website has 4 pages:

  • Home
  • About
  • Frequently Asked Questions
  • Who We Are

This website is actually a GitHub website, based from the ohi-science organization. Its url is really ohi-science.github.io/toolbox-demo, but we have redirected ohi-science.github.io to the ohi-science.org domain. What this means is that there is a Github repo behind this website, and you can navigate to it because we know the username and repo name:

http://ohi-science.github.io/toolbox-demo <=> https://github.com/ohi-science/toolbox-demo


12.2.2 The website’s gh-pages branch

Let’s go to https://github.com/ohi-science/toolbox-demo.

This looks familiar to you, these are the files in your tailored repository. But that is because we are looking at the master branch. Master is the default branch name, and we haven’t paid attention to branches until now. Click on the master branch, and this will let you select an existing branch, or create a new one. We want to select the existing gh-pages branch, which was created along with your tailored repository.

The gh-pages branch - this is critical for building free webpages. You can usually create and name branches whatever you want, but the gh-pages name is special: it means it can be built as a website. (We won’t focus on what branches beyond this in this training, but they are really powerful for collaborative analysis with teams. I think of them like parallel universes).


Now let’s look at the filenames. When we switch to the gh_pages branch, we get a whole new set of files. We can recognize the names of the webpages we’ve seen, and there is also a _site.yml file, which is the website’s configuration file. The simplest website possible would have 2 files only: _site.yml and index.Rmd

You’ll notice that there are some pages like “scores” and “goals” that exist here but do not show up on the website. We will talk about this more later, but you do not have to include all your pages in the navigation bar. This is nice when pages are under development.


12.2.3 Get the website’s branch on your computer

You likely already have forked and cloned the toolbox-demo to your own computer. (If you haven’t done so, follow the prerequisites at the beginning of the chapter).

In RStudio, go to the Git Tab. You can click on “master” on the top-right. This will show the local branches that are available to you (only “master”) and also the branches that are available remotely on github.com (“master” and “gh-pages”).

To be able to switch between branches nicely like we were able to from GitHub.com, we need to bring the remote gh-pages branch locally. We need to do a one-time setup, and we will do this from the command line, also called the Terminal. Luckily, the newest versions of RStudio have a terminal available from within RStudio, so let’s take advantage of this.

First, click on terminal. Second, type git checkout gh-pages. Third, see that you are now on the gh-pages branch, with the ability to switch between them by clicking. You will need to save, commit, and push your work before switching.

You’ll also see that the file pane now has all of the gh-pages files!

Note: if you had a file from the master branch open in your RStudio editor, you may get a message saying that this file has been deleted, should you close it? This can be alarming, but remember that file does not exist in this gh-pages branch. We are in a different space (a different parallel universe) and that file is not here. It’s OK to close it, it still exists in the master branch (you can go to github.com and check out the master branch to confirm!)

Now, we can start exploring and editing our website!

12.3 Basic Workflow

Until this is developed, please see the basic workflow chapter from the “Making free websites with RStudio’s R Markdown” tutorial.

And practice committing, pushing, and switching branches back to master! RStudio will remind you to pull when you switch branches if need be.