Deploying xaringan Slides with GitHub Pages

Thu, 18 Nov 2021 00:00:00 +0000

Silvia Canelón is a researcher, community organizer, and R educator. Her research leverages electronic health record data to study pregnancy-related outcomes, and her organizing values data literacy and communication as ways to build power and effect change.

This post will guide you step-by-step through the process of creating an HTML xaringan slide deck and deploying it to the web for easy sharing with others. We will be using the xaringan package to build the slide deck, GitHub to help us host our slides for free with GitHub Pages, and the usethis package to help us out along the way. You will get the most out of this workflow if you are already familiar with R Markdown and GitHub, and if you have already connected RStudio (or your preferred IDE) to Git and GitHub.¹ The post will not cover the nuts and bolts of xaringan or talk about slide design & customization, but you can find lots of learning resources listed at the end.

Choose your own adventure

Option 1: Start at the beginning of the workflow to make a slide deck using the R Markdown template built into the xaringan package. The built-in template doubles as documentation for the xaringan package, so it is a great way to familiarize yourself with the package features, but it also includes a lot of content that will probably want to remove and modify when creating your presentation.
Option 2: Start with an R-Ladies themed xaringan template (embedded below). This is an example slide deck originally created as a teaching tool to highlight some of the main features of the xaringan package, and to demo some customization that incorporates the R-Ladies CSS theme built into xaringan. Please feel welcome to use/modify it to suit your needs! When you are ready, you can follow the steps immediately below 👇 to download the files to your machine, 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.

Try navigating through the slides ☝️ 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

Packages

This workflow 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")

📍 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 ✅

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:
https://github.com/spcanelon/RLadies-xaringan-template

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:² “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! 🚀
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:
https://spcanelon.github.io/RLadies-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.)

13. This GitHub Pages workflow is not exclusive to xaringan slides! Try it out with any other HTML file.

Learn more

Foundation

Sharing Your Work with xaringan • Silvia Canelón – workshop site
Introducción al Paquete xaringan • Silvia Canelón – R-Ladies Meetup
Making Slides with R Markdown • Alison Hill – workshop slides
Presentation Ninja • xaringan Official Document – package documentation
Chapter 7 xaringan Presentations • R Markdown: The Definitive Guide – book chapter

Making your slides extra special

Professional, Polished, Presentable • Garrick Aden‑Buie & Silvia Canelón • useR!2021 – workshop site
Home · yihui/xaringan Wiki • GitHub – wiki of customizations for xaringan
Making Extra Great Slides • Garrick Aden‑Buie – talk & slides with xaringan overview and featuring CSS styling and xaringanthemer
Applying design guidelines to slides with {xaringanthemer} • katie jolly – blog post
A playground of extensions for xaringan • xaringanExtra – package site
Custom xaringan CSS Themes • xaringanthemer – package site

Note from the Editor: Silvia’s post is a mini masterpiece of clear, concise writing that elucidates complex technology within the narrow context of explaining a single well-defined task. Silvia does not attempt to say everything she knows about the subject, and she resists digressions that might obscure the path she is laying out. It is an example of achieving clarity through saying less.

How to share R visualizations in Microsoft PowerPoint

Thu, 04 Apr 2019 00:00:00 +0000

Hadrien Dykiel is an RStudio Customer Success Engineer

Microsoft PowerPoint is often the de facto choice for creating presentation slides, especially at larger companies. In many organizations, it comes pre-installed on workstations and pretty much everybody knows how to use it. This can make it an effective medium for sharing information, since most folks are comfortable with it. Unfortunately, valuable time is often lost manually creating slides. R developers often find themselves copying and pasting their results into presentation decks. Moreover, results may change or over time, requiring analysts and data scientists to manually update their slides with the latest results. So, in addition to being a time-consuming task, copying and pasting also introduces a big reproducibility problem. R can help solve these problems by programmatically exporting your results to PowerPoint for you.

Let’s say you are collaborating on a project in which members of your team will use other tools like SAS and Excel to perform their analyses. At the end of the day, you plan to combine all of your work together into a single presentation deck that will be shared with various business stakeholders. You boot up RStudio and open an R Markdown file and produce a correlation plot for the presentation.

Rather than manually copying and pasting your corrplot into the final PowerPoint deck, you can update the output document type in your document’s YAML header to powerpoint_presentation. Optionally, you may also want to customize the appearance of your slides by passing a custom reference document via the reference_doc option. This is a nice option to use if you want your slides to match your company’s color schemes, for example. The snippet below shows what the code for a typical rmarkdown file with the output format set to PowerPoint might look like. Like all .Rmd files, it contains three elements: a YAML header that contains the metadata for your RMD file, narrative in simple markdown syntax, and code.

As soon as you hit the Knit button (or use the keyboard shortcut Cmd/Ctrl + Shift + K), RStudio initiates the knitting process. The rmarkdown package transforms your R script into markdown, and the pandoc package converts it to the PowerPoint output format, as specified in your YAML header. This process happens all underneath the hood, so as a user, the only thing you see is the final PowerPoint output file, which automatically opens as soon as your document finishes knitting. Because you created your PowerPoint slides programmatically, you can easily update them in the future, such as if new data becomes available and you wish to refresh your results.

The rmarkdown package offers a fair amount of flexibility for customizing your PowerPoint slides, such as having the ability to include R code, images, R visualizations, speaker notes, and customized column layout.

To learn more about creating PowerPoint presentations with R, Yihui’s RMD: The Definitive Guide and RStudio’s article Rendering Powerpoint Presentations with RStudio are both great resources.

R Markdown on R Views