Why R Markdown?

Why R Markdown?

Activity

TIME: ⏱ 10 minutes

Let’s use the postcards package to make a simple, single “about” page right now, and publish it with GitHub Pages.

Pre-requisites

First, make sure you have the latest version of the postcards package installed from CRAN:

install.packages("postcards")

Restart your R session. If you use RStudio, use the menu item Session > Restart R or the associated keyboard shortcut:

• Ctrl + Shift + F10 (Windows and Linux) or
• Command + Shift + F10 (Mac OS).

packageVersion("postcards")
[1] ‘0.2.0’

Create GitHub repo

We’ll follow a “New Project, GitHub first” workflow.

Go online to your GitHub account, and create a new repository and YES initialize this repository by adding a README file.

Clone GitHub repo

We just created the remote repository on GitHub. To make a local copy on our computer that we can actually work in, we’ll clone that repository into a new RStudio project. This will allow us to sync between the two locations: your remote (the one you see on github.com) and your local desktop.

Use the RStudio IDE project wizard:

1. Open up RStudio to create a new project where your website’s files will live.

2. Click File > New Project > Version Control > Git.

3. Paste the URL from GitHub (either HTTPS or SSH).

4. Be intentional about where you tell RStudio to create this new Project on your workstation.

5. Click Create Project.

Alternatively, do this (but note that it requires a GitHub personal access token):

usethis::create_from_github("apreshill/iyo-postcard", 
                            destdir = "/Users/alison/rscratch")

First commit & push

Everyone - all together now!

Use the RStudio IDE to commit and push these files:

• *.Rproj

• .gitignore

Create a postcard

Inside your current postcards project, use the R console:

library(postcards)

Then you could run (wait- don’t do this yet!):

create_postcard()

But you could also pick one of four templates:

1. "jolla" (https://seankross.com/postcards-templates/jolla/) [the default]

2. "jolla-blue" (https://seankross.com/postcards-templates/jolla-blue/)

3. "trestles" (https://seankross.com/postcards-templates/trestles/)

4. "onofre" (https://seankross.com/postcards-templates/onofre/)

create_postcard(template = "jolla") #default
create_postcard(template = "jolla-blue")
create_postcard(template = "trestles")
create_postcard(template = "onofre")

Anatomy of a postcard

YAML, body, name is index- this is special

In your YAML, note:

output:
  postcards::trestles

This is your output format! More generally, <package>::<template>. When you knit 🧶 (next section), the RStudio IDE detects this YAML key and knits to the appropriate output format.

✨ Commit & Push! ✨

You should be committing these files:

• index.Rmd

• *.jpg

But! There is no .html file (yet…)

Knit the postcard

Knit button 🧶, or:

rmarkdown::render("index.Rmd")

What is new in your Git pane?

✨ Commit & Push! ✨

You should be committing this files:

• index.html

(You may get a warning in RStudio IDE that this file is too big- go right ahead)

Edit your postcard

Social & other links go in the YAML, some templates (like trestles) have content in the body.

Publish a postcard

Easy:

• Publish to GitHub Pages via github.com:

https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site#creating-your-site

Medium:

• Use the usethis package to configure GitHub Pages from R:

> usethis::use_github_pages(branch = "main", path = "/")
✓ Setting active project to '/Users/alison/rscratch/iyo-postcard'
✓ Activating GitHub Pages for 'apreshill/iyo-postcard'
✓ GitHub Pages is publishing from:
● URL: 'https://apreshill.github.io/iyo-postcard/'
● Branch: 'main'
● Path: '/'

Share your postcard!

Add it to your repository details ❤️