Deploying xaringan Slides: A Ten-Step GitHub Pages Workflow

spcanelon · September 9, 2021, 7:49pm

Category: Entry Point into a Topic
Repo: https://github.com/spcanelon/silvia/blob/main/content/blog/2021-03-16-deploying-xaringan-slides/index.Rmarkdown

Note: This workflow is not exclusive to xaringan slides! Try it out with any other HTML file.

Choose your own adventure

Option 1: Keep reading to make a xaringan slide deck from scratch!
Option 2: Start with an R-Ladies themed xaringan template (see below)

I made an R-Ladies themed xaringan template to use as a teaching tool and you are welcome to use/modify it to suit your needs! You can download the files to your machine r emo::ji("point_down") and then skip down to Initialize version control with git

usethis::use_course(
  repo_spec = "spcanelon/RLadies-xaringan-template",
  destdir = "filepath/for/your/presentation"
  )

Note: After copying the files to your machine you'll probably want to rename the file folder to whatever makes sense for your presentation.

xaringanExtra::embed_xaringan("https://spcanelon.github.io/RLadies-xaringan-template", 
                              ratio = "4:3")

Try navigating through the slides r emo::ji("point_up") with your left/right arrow keys and press the letter "P" on your keyboard to see some notes in Presenter View

The Ten-Step Workflow

This workflow assumes you have already connected RStudio to Git and GitHub.^[1]

Packages

This code-through was developed using:

Software / package	Version
R	4.0.3
RStudio	1.4.1103
`xaringan`	0.19
`usethis`	2.0.0

install.packages("xaringan")
install.packages("usethis")

Creating your xaringan slide deck

1. Create a new RStudio project for your presentation:

usethis::create_project("filepath/for/your/presentation/repo-name")

r emo::ji("round_pushpin") If you're not sure where you are on your computer, check your working directory with getwd() and use it as a filepath reference point

2. Create a xaringan deck using a xaringan template:

File > New File > R Markdown > From Template > Ninja Presentation > OK

3. Delete what you don't need and save your R Markdown file with whatever name you like. If you pick index.Rmd the live link you share at the end will be relatively short.

4. Render HTML slides from the open Rmd file using xaringan's infinite moon reader:

  xaringan::infinite_moon_reader()

Initialize version control with git

5. Initialize version control of your slides with git:

usethis::use_git()

You'll be asked if you want to commit the files in your project (with the message "Initial commit") and then if you want to restart to activate the Git pane. Say yes to both r emo::ji("check")

Note: At the moment {usethis} names the primary branch "master" by default. Issue #1341 suggests the option to instead name it "main" is in the works.

6. Connect your local project with a GitHub repo:

usethis::use_github()

You could use the function argument private = TRUE to create a private GitHub repository. But you may have to remember to change the visibility before deploying to GitHub Pages.

7. Your new GitHub repo with all of your xaringan project files will automatically open up in your browser

Repo for the R-Ladies xaringan template:

GitHub - spcanelon/RLadies-xaringan-template: Xaringan presentation template with an R-Ladies theme

Making and committing changes to your slides

8. Edit your slides as you wish. Commit often! And then push to GitHub. Use the tools provided by the Git pane in RStudio, or use the following commands in the Terminal:

# Step 1: Stage all modified files
git add .

# Step 2: Describe the changes you made to your files
git commit -m "<A brief but descriptive commit message>"

Consider writing a commit message that finishes the following sentence:^[2] "If applied, this commit will..." (e.g. "Change the slide theme", "Add hello slide")

# Step 3: Push the changes to your GitHub repository
git push

Deploying your slides

9. When you're ready to deploy your slides, you can use the usethis::use_github_pages() function which makes the process of deploying via GitHub Pages super easy. I recommend pointing branch to the name of your primary branch.

usethis::use_github_pages(branch = "master")

Note: Your repository must be public for your deployed slides to be available publicly, unless you have a paid GitHub account.

Also, you only need to follow this step once to deploy your slides to the web. As long as you remember to push to your repo any changes that you make to your slides (Rmd and HTML), GitHub Pages will know how to render them.

10. Visit the link provided to see your newly deployed slides! r emo::ji("rocket")
Don't panic if you don't see them right away, sometimes it takes a little time. This is the link you will share with the world when you present. Notice it looks very similar to your GitHub repo link.

Link to the R-Ladies xaringan template rendered slides:

R-Ladies Themed xaringan Template

Bonus steps

11. Go to the repository home page and find the About section on the right hand side. Add a description of your presentation and the link to your slides, that way your presentation is easily available to anyone visiting your repo.

12. Check out Garrick Aden-Buie's blog post Sharing Your xaringan Slides to learn how to create a social media card for your slides and use your new link to share your slides in more places (e.g. embedded on a website, etc.)

Learn more

This is a submission to the R Views Call for Documentation. For more information see rviews.rstudio.com.

Deploying xaringan Slides: A Ten-Step GitHub Pages Workflow - R Views Submission