Prerequisites

R Markdown

R Markdown is a file format for making dynamic documents with R. An R Markdown document is written in markdown (an easy-to-write plain text format) and contains chunks of embedded code. R Markdown files are designed to be used with the rmarkdown package. rmarkdown comes installed with the RStudio IDE.

R Markdown provides an authoring framework for data science. You can use a single R Markdown file to both

  • save and execute code,

  • generate high-quality reports that can be shared with an audience.

R Markdown documents are fully reproducible and support dozens of static and dynamic output formats. In this section, we will learn how to convert an R Markdown file into html files.

Building a website

Creating a repository on Github

  • Open GitKraken, make a new repository web_test by clicking Start a hosted repo, then fill the information, and save this repository locally (e.g., C://web_test/).

  • Download this demo, decompress it, and copy all items (including files and folders) to the local repository folder web_test.

  • Stage and commit all changes, and push the local repository to Github.

Home page

Each website requires a .Rmd file named index.Rmd, which provides the content for the home page of your website. Take the demo as an example, the index.Rmd provides a basic description of the website.

---
title: "My Website"
output:
  html_document:
    df_print: paged
---

Welcome to my website!  
I am a student at SUSTech, my research area is about xxx.

Here lines 1-6 mean that the output file will be in html format. And lines 8-9 can be replaced by real information.

Global YAML header

Another necessary file is _site.yml, which provides the global YAML header for the whole site. In the demo, the _site.yml is written as:

name: "My Website"
output_dir: "docs"  # docs directory of master branch
navbar:
  title: "xxx's website"
  type: inverse
  left:
    - text: "Home"
      href: index.html
    - text: "Page1"
      href: Page1.html
    - text: "Page2"
      href: Page2.html
    - text: "Page3"
      href: Page3.html      
    - text: "Page4"
      menu:
        - text: "Page4.1"
          href: Page4.1.html
        - text: "Page4.2"
          href: Page4.2.html
        - text: "Page4.3"
          href: Page4.3.html   
output:
  html_document:
    theme: cerulean
    highlight: pygments

Here we define a home page with index.Rmd. Page1 to Page2 are static pages, and Page4 has a drop-down menu.

theme specifies the Bootstrap theme to use for the page (themes are drawn from the Bootswatch theme library). Valid themes include:

  • default
  • cerulean
  • journal
  • flatly
  • readable
  • spacelab
  • united
  • cosmo
  • lumen
  • paper
  • sandstone
  • simplex
  • yeti

You can check the above themes at this gallery. Pass null for no theme (in this case, you can use the css parameter to add your own styles).

highlight specifies the syntax highlighting style. Supported styles include:

  • default
  • tango
  • pygments
  • kate
  • monochrome
  • espresso
  • zenburn
  • haddock
  • breezedark
  • textmate

Pass null to prevent syntax highlighting.

More about _site.yml can be found here.

Markdown Syntax

See Page1.Rmd for basic syntax in R Markdown. More are available at this R Markdown cheat sheet.

Build a site

You can check the current page by clicking Knit, a new window will pop up to show the html file.

Finally, when everything looks fine, set the working directory to the local repository (in this case, C://web_test/). In R console, run:

rmarkdown::render_site()

In the demo, a website (and all html files) will be created in docs/. New your website is ready to be launched.

Publish the website on Github

Go to Github:

  • Open the remote web_test repository on Github
  • Click Settings
  • Under GitHub Pages section, use main branch and /docs folder, then click save. You may receive an error email from Github, this is because remote repository is not updated yet. Ignore this error for now.

Open GitKraken, stage and commit all changes. And wait for a few minutes as Github is publishing the website.

You should be able to view your website at: https://xxx.github.io/web_test/, where xxx is your Github user name.

General workflow of updating the website

  • Step 1: Make changes to the source files (.Rmd)

  • Step 2: Check and verify with knit

  • Step 3: Re-build the website with rmarkdown::render_site()

  • Step 4: Stage and commit changes with GitKraken

  • Step 5: Push with GitKraken, and wait for a few minutes for updates take place. If you get an error message email from Github, go back to Step 1-4, fix the bug(s), and push again.

In-class exercises

Exercise #1

Launch your own website. When it’s ready, share it with the class.