Sharing on Short Notice

Thanks to everyone who joined us for last week’s webinar on how to share your teaching materials online— on short notice— with R Markdown. We weren’t able to get to all of the questions that were asked during the webinar, so here are answers to all of them.

Slides at https://rstd.io/sharing
https://github.com/rstudio-education/sharing-short-notice
Video
If you have any other questions, please don’t hesitate to post on RStudio Community

Questions about R Markdown

I’m a newbie to R Markdown. I’m a writer but not really a coder. Where can I start to with all this?

RStudio has some self-paced online tutorials for getting started with R Markdown. Also, the Communicate section of the book R for Data Science gives a great overview of the basics of R Markdown. To learn about the different types of output formats available, we recommend R Markdown: The Definitive Guide by Yihui Xie, J. J. Allaire, and Garrett Grolemund.

For the website building tools we covered, here are some specific resources:

• R Markdown websites
• Distill
• Bookdown
• Blogdown

Figure 1: A climb up R Markdown Mountain

How can you incorporate learnr exercises in R Markdown HTML output?

This is a bit tricky, but possible! Desirée has done this extensively on her Teacupes, Giraffes, and Statistics R Markdown website. She also wrote a blog post with instructions.

Figure 2: Embedding learnr in R Markdown

Questions about the RStudio IDE

My RStudio IDE doesn’t have Build. Could you share how to show it?

Somtimes you’ll need to restart the RStudio IDE to detect the output format and show you the correct “build” button on the Build tab.

Figure 3: Build tab in the RStudio IDE

Here is a bit more discussion on this, and how to use the .Rproj file to debug (hint: you are looking for BuildType: Website!).

Questions about Netlify

Because we focused on how to share your teaching materials online on short notice, we introduced Netlify Drop. Here are a few questions about that.

Can you change the name of the Netlify link (while keeping the Netlify subdomain)?

Yes! By default, Netlify provides you a sometimes amusing, random Netlify subdomain. See this slide for how to change your site name, keeping the Netlify domain ___.netlify.com; the video below walks you through those steps.

Can you choose a web address for Netlify?

Yes! The Netlify docs contain instructions for setting up custom domains.

Any preferences between using Netlify vs. Travis-ci for continuous integration?

I use Netlify mainly for continuous deployment. This means that I connect Netlify to a Git repository and the two things- my source files and my website- are kept in sync. Then every time I commit and push changes to Git, my updated website automatically deploys without me having to remember to manually update my site.

For blogdown websites, this workflow is particularly nice because Netlify can use Hugo to build my site from my source files, but I still need to serve the site locally first because Netlify does not know R.

Travis does know R, so I have used that for continuous integration of HTML books created with bookdown, as with the Stat545 website. Lately, many users are testing out GitHub Actions with R Markdown-based sites with success. For example, Emil Hvitfeldt wrote up some great instructions for using GitHub Actions with Netlify for a bookdown book. Similarly, here are some instructions for using GitHub Actions with a blogdown website, which is set up for the tidyverse.org site. There is a ghactions R package that can also help.

Can you make a private site using Netlify for free?

No, site passwords are not in Netlify’s free tier.

Questions about bookdown

Can bookdown export to PDF or Word docs as well as HTML?

Yes- the bookdown package enables several different output formats. We focused on only one of the HTML output formats: the GitBook style.

I tried the Netlify Drop and worked great. I tried afterward to link it to the respective GitHub repository, but when it tried to build it I got an error. I used the build command npm run build, and the directory _book.

Netlify cannot build your book for you- your bookdown book needs to be built with the bookdown R package in RStudio. When you use Netlify, you don’t use a build command at all, but you should change the publish directory to the _book/ sub folder.

Questions about blogdown

Is it waaaaaay simpler to use Blogdown?

No. This blog post by Maëlle Salmon, who has developed several Hugo websites using blogdown including ROpenSci and R-Hub Documentation, is a great overview of what you need to know. As we mentioned in the webinar, unless you have high HTML fluency and high degree of comfort working with websites, we don’t recommend you start here if you are sharing on short notice and this would be your first blogdown project.

Why does signing up to Netlify using a version control account make your life easier?

Wiring up your version control account (i.e., GitHub, BitBucket, GitLab) with Netlify is a good thing ™️. This is because it enables you to continuously deploy your website, so that every commit/push that changes your source files triggeres the site to be re-built.

What should I do if I want to update the blogdown theme?

First, I do not recommend updating your blogdown theme while teaching a course. Ask me how I know.

Figure 5: Alison's blogdown advice

But, if you must update an already installed theme like for example "gcushen/hugo-academic", use:

blogdown::install_theme("gcushen/hugo-academic", 
                        force = TRUE, 
                        update_config = FALSE,
                        theme_example = FALSE)

Then, I would look at the new example site, now located in themes/hugo-academic/exampleSite. First, look at the site configuration files (config.toml plus any .toml files in config/_default/) and update manually. You’ll also want to look at the YAML in the updated example site to see if that changed as well.

It is possible to deploy a blogdown site, not in Netlify, but in Github?

Yes it is possible.

Questions about “behind the scenes”

How did you make such neat screen recordings? They were great for teaching!

Desirée made the videos in the webinar using a Mac OSX app called Kap, an open-source screen recorder. Here is an example video, which shows how to use the “Deploy to Netlify” button we demoed from this GitHub README:

In the Kap app preferences, we selected “Highlight clicks”, which creates that circle halo around the cursor when you click on the screen (you can see it about 7 seconds in to the video above). She also magnified the mouse pointer by changing an OS-specific setting before recording.

Thank you

We really enjoyed making and delivering this webinar. We have so enjoyed seeing all the sites already built and shared so far!