R Markdown to GitHub Pages

A concise legacy R Markdown workflow for publishing small GitHub Pages sites, now preserved with a Quarto-era maintenance note.

R Markdown into GitHub Pages

Maintenance note: this post preserves a compact R Markdown workflow for small GitHub Pages sites. For this blog itself I have since moved to Quarto, which makes project configuration and rendering cleaner, but the original R Markdown approach is still useful for lightweight sites.

Example of one of my GitHub pages:

You might have read this GitHub and RStudio tutorial while searching this topic. It is quite long because it teaches Git at the same time. For a small static site, you do not need those branch operations. The example YAML code is also easy to mis-indent, so I corrected it below.

Here is the short version:

1. Create in the root directory a yaml file: “_site.yml”

Make sure the YAML is indented correctly. Most errors come from malformed .yml files. For example, I get the error “Format is not of class rmarkdown” if I remove one space before theme: cosmo.

The following example as in the tutorial (format corrected) creates a navbar with website title “Cars”, home page named “HomePage” (using index.html) and another page called “Page 1” (using speed-and-distance.html).

The HTML filenames in href should match your R Markdown HTML output. I would usually name the .Rmd files with the same base names.

name: "cars"
output_dir: "docs"
navbar:
  title: "Cars"
  left:
    - text: "HomePage"
      href: index.html
    - text: "Page 1"
      href: speed-and-distance.html
output:
  html_document:
    theme: cosmo

How the navbar on the site looks like

Here is another example, the yaml file for the sample page posted in the beginning, you can check the repo to see how are the files organized.

name: "COVerAge_Plot"
output_dir: "docs"
navbar:
  title: "HOME"
  left: 
    - text: "Plots for COVerAGE-DB"
      href: index.html
    - text: "Country profile"
      href: country_report.html
output:
  html_document:
    theme: cosmo

2. Remove the knit and output part from the heading of .Rmd files so they do not need their own output fields anymore.

---
title: "Speed and Distance"
---

3. Render site

This will render every .Rmd file in the root directory.
Think the GitHub page as a one-page site with index.html as the homepage.

rmarkdown::render_site()

4. Push to GitHub

Make sure the homepage is named index.html. Go to repository settings -> GitHub Pages and point the source to the folder containing this index.html file. You can also change the theme using the “Theme Chooser”.

GitHub Page

You can only assign the short domain names like liuyanguu.github.io to one repo by changing the name of your repo into this URL (in my case, this blog, I have a repo named liuyanguu.github.io). All the rest pages and sites hosted on GitHub will have the repo name attached behind: liuyanguu.github.io/COVerAge_Plot (although this is not a page on this blog).