Resources
Mar 2, 2021 |
56 min
|
4.7k views
|

Alison Hill & Desirée De Leon | How to Get Your Materials Online With R Markdown | RStudio (2020)

Full title: Sharing on Short Notice: How to Get Your Teaching Materials Online With R Markdown

Educators create a lot of files for teaching- slides, exercises, solutions, assignments, data, figures- that all ultimately need to be shared with other people. Having a link for sharing your teaching materials can save you time and pain, but it is hard to get started if you’ve never shared your resources online before. In this webinar, we’ll give a tour of the R Markdown ecosystem for educators that you can start to use right away. We’ll show how it can help you make your teaching more shareable, reproducible, and resilient.

About Alison:
I studied psychology and quantitative methods, receiving my Ph.D. from Vanderbilt University (2008). For eight years, I was a professor and scientist at Oregon Health & Science University, where my research was funded by the National Institutes of Health, the Oregon Clinical and Translational Research Institute, and Autism Speaks. I have written numerous scientific journal articles and book chapters on autism and neurodevelopmental disorders. I have developed and delivered workshops, graduate-level courses, and curricula based on teaching R, the tidyverse, and literate programming. You can follow my current work for RStudio Education on GitHub.

About Desirée:
I am neuroscience PhD student at Emory University and also a former summer intern at RStudio. This past summer, I worked with Alison Hill to develop a handbook filled with practical advice and resources for educators who teach with R and RStudio. I enjoy spending my time on collaborative projects that involve coding, teaching, and illustration.

image: thumbnail.jpg

Transcript#

This transcript was generated automatically and may contain errors.

Welcome, everyone, to the webinar on sharing on short notice, where we'll show you how to get your teaching materials online with R Markdown.

So, hello, we're really happy you could join us today. We know that everybody has a lot of things going on, so we appreciate you taking the time to join us this afternoon.

My name is Allison Hill, and I'm a data scientist and professional educator at RStudio. And I'm Desirée De Leon, and I interned with Allison last summer at RStudio on the education team.

And even though we don't have a video feed in this webinar, we promise we are real-life humans who are also stuck at home just now, like you all, sitting in front of our computers.

And one thing that Desirée and I both have in common is that we ship a lot of websites. I'm a developmental psychologist, Desirée is a neuroscientist, neither of us is a web developer, but we both ship a lot of websites for teaching data science. And here are just a few of them.

If you type the short link on the bottom of our slides, it's rstd.io forward slash sharing, you'll be able to see our slides and follow along in your browser. So you can see all of these links are also clickable for you. Each of these sites was built using R Markdown with different tools chosen depending on what we needed. So that's us.

Who this webinar is for

Who are you? We think you're an educator. And you have R Markdown files that you use for teaching. But they may be stuck on your computer, and you need to share them easily with others without filling up their inboxes.

And that's because you probably have a new classroom space that looks like this. So sharing needs to be done 100% online. And you might feel like this right now, everything seems to need your attention, but you cannot do everything.

So with that in mind, today, we'd like to give you a quick tour of the R Markdown tools that you can use to get your course materials online on very short notice. We'll show you how to build a course website to help you teach and reach learners using R Markdown and friends. And our goal is to give you a quick boost to help you get your site up off the ground with a shareable link so that you can get on with your teaching and hopefully avoid crashing in the process.

So why make a course website at all? I think of it as a way, first, to help me organize my own stuff, to get all my piles of teaching documents into some kind of order. And that makes it more reproducible for myself and for others. But it's also a way to make my teaching more resilient. If I'm organized and online, I can be more nimble when changes need to happen. And a side benefit of all that is that it also makes it more shareable. So it makes it easier for learners, too, because they see what I see.

Building a single R Markdown file

So we'll be building websites with R Markdown. And because of that, we'll start by talking about building a single R Markdown file. So Desiree, you're up. All right. Thanks, Allison.

So let's see. Jumping right in, what does an R Markdown file look like? So here's an R project folder for a lab, let's say. And inside that folder, you'll notice an R project file. And opening that file in RStudio takes us here, where we can see our single R Markdown file. And as I mentioned, this is one for a lab that's going to visualize data from the Museum of Modern Art.

So let's just quickly walk through some of the key parts of this file. It starts with metadata written in YAML, which is a list of keys on the left and their values on the right. And the first key you see is title, which is, in this case, Lab 02 MoMA Museum Tour. And the last section is all about output in the YAML. So here, the output is an HTML document. And beneath that, we can add options to our HTML document, for example, a table of contents with the key TOC set to true. So that's the metadata.

But the real meat in your R Markdown file is text written in Markdown and, of course, code written in R. So these three things, metadata, text, and code, make up an R Markdown document.

So, of course, Desiree, the real magic happens when you click on the knit button and see your file turned into HTML. So when we click on the knit button, we can watch the build happening in the bottom pane. Our Markdown document gets processed. And you can see the rendered HTML file locally. You can also choose to open it up in a bigger browser and explore around by clicking on it, testing a few things out.

So here's a screenshot of what we just showed you, what we knit. And we can see that using the theme key in our YAML, we were able to apply changes to our fonts and colors. And we have this nice table of contents that's floating off to the side. But this is still local and stuck in my computer. A link would make it a lot easier to share with learners. So how do we start sharing?

Deploying to Netlify

First, we need a web server, which is basically a big computer in the clouds and a hat tip to Heather Nolas for that analogy. And for this webinar, we're going to use a web server provided by Netlify. So we're going to drag and drop that project folder into Netlify. And this is going to put our web page online. So Allison, let's go ahead and do our first drag and drop.

Happy to, Desiree. So I open up my browser, go to app.netlify.com forward slash drop. And I type very slow. And then I'm going to see that little box where it says drag and drop your site folder here. I'm going to take that lab 2 folder and drag it right into that box. You can see Netlify things for a second. And now my site is live. And it gives me a nice random link, friendly Borg, that I can now share with whomever I choose. Hooray.

All right. Hooray. We have deployed to Netlify. But just as a quick summary of what happened. So we started with an R Markdown file. And it was named index. We knit this to convert it to Internet ready HTML file. That looked great. But it still only lived locally in our R project folder. So we had to drag and drop it into Netlify, which deployed our page and generated a link. Woohoo.

Building an R Markdown site

Okay. But this is just one R Markdown file. And we want to be able to share many R Markdown files. So we're going to hike Markdown Mountain today. And our goal for the rest of this webinar is to show you four R Markdown tools that are for turning a collection of R Markdowns into a website.

And we're going to start with the classic R Markdown site. So to make one, you just need the R Markdown package installed, which is already done for you if you use RStudio. And here's an R Markdown site for a course about data visualization. This is just a screenshot. But you can go to the link above it. And actually, the MoMA lab that we just turned into a webpage was one of the labs from this course. Now, this course website is a place to share all of those labs. And the biggest addition that we see here is a top navigation bar. Which allows us to link to other webpages, including ones made with R Markdown, like this page with slides and readings. Or other websites, like this one here, which goes to a learning management system.

All right. So let's build a minimal R Markdown site of our own. Imagine that this box on the left is a list of files that are inside of our R project folder. And to knit all of these pages into our R Markdown site, you can mouse over to the build tab in RStudio and then click build website. And after we've done that, we see that it's added a new folder called underscore site. And that's where all of our HTML files live. And then we can also see the site we just built locally. We have a nav bar, a theme, and in this case, even a dropdown menu.

So let's look under the hood at some of these files. And we'll start with index.RMD. Index is a special file name in any website, because it always becomes the home page. So if each of our R Markdown files in our site was a hot air balloon here, index would be the first one you see. And if we take a peek inside index.RMD, we actually don't see anything very special. In fact, you can actually take any existing R Markdown document that you already have, rename it index, and turn it into your site's home page.

The next file is underscore site.yaml. And this is new. So this file is in charge of tying all of the pages together. And it's a site configuration file written in YAML. And let's take a look inside of that. So the first thing you may notice is that this is a YAML file, so there are no fences. It's just a list of keys and values. And the first key that we see is nav bar. And this is what lets you build your site's navigation. There's a key for title in this site.yaml. And whether we want our links to be on the left, but you could also put them on the right. And if we want links listed in a dropdown menu, we can do that too from this file. And for all the pages you link to in your nav bar, there's a key called href that needs to point to an HTML file, even though you're using R Markdown files as your source. You need to make sure that it's always going to an HTML file. And finally, we can set up a theme that will apply to all of the pages throughout our site.

And as for other R Markdown pages, there's nothing special about them either. As long as you link to a page in your underscore site YAML, you can take any existing R Markdown file and turn it into a page in your site.

So a quiz, Allison. Here is a page that's a lab page in our website. What do you think the YAML for this lab page looks like? Oh, good question. I think that this YAML has table of contents, TOC, as one of the keys that's set to true. And I see it's floating off to the left. So I think TOC underscore float is also set to true. And I see my favorite code download key. So code underscore download, I believe, is true also, which allows you to click on that nice little download RMD button, and somebody can download your source RMD file. Okay, Allison, good job. That's exactly what we see.

You can set the YAML for each page if you want. It doesn't only have to be done in the underscore site YAML file. And if you want the output options to apply to every single page, that's when you would choose to put it in the underscore site YAML file as opposed to the individual page. But okay.

Sharing the R Markdown site

So finally, we are ready to share our Markdown site. And we'll do this the same way as we did before. As a reminder, all of our HTML website-ready pages are stored in this underscore site folder. So this is the only folder that we need to drag and drop. So Allison, can you take it away again? I will.

So here we're back at app.netlify.com forward slash drop, and we're dropping that underscore site folder right in. And we're able to get a link, Hardcore Goldwasser. Great name. Website.

So one thing you may have noticed with what Allison just showed you is that there's a note from Netlify, and it says, unclaimed sites are deleted after 24 hours. So we have to actually create an account with Netlify to keep our site online permanently. So let's actually go back to Netlify and do that.

So we click on that little sign up for Netlify button, and you can sign up with an existing version control account like GitHub, GitLab, or Bitbucket. So if you have one, I encourage you to use those to sign into Netlify, because that'll make your life easier.

And today we're going to actually sign up with an email address. So Desiree's entering an email address, signing up for an account with Netlify. She's waiting on instructions for how to verify her account. And we have it. And we will be able to own, was it Hardcore Goldwasser forever? So now it's part of her team on her Netlify account, and your silly named link is now here to stay.

All right, great. Okay. But after I've deployed my site, what happens if I decide that I want to make a change?

So let's say, for example, looking at the YAML file on the left side, say that I want to change my theme to something named United.

So once I make that change, I need to remember to rebuild my website. And then I need to be able to drag and drop again. So let's see what that process looks like.

Sorry, my mouse has gone missing. There we go. Okay. Okay. Okay.

So once we've rebuilt our site with the changes that we want, we can just use that underscore site folder again, but we have to go into deploys in our Netlify UI. And then you see this little box, need to update your site, drag and drop your site folder here. So this means that we get to keep that link, the Hardcore Goldwasser link, and update the same link with our new content.

So if we drag and drop it again, it takes a second to think, and it republishes. So now if we click on the link, we can see that our new theme, the United theme, has been applied. So it looks a little bit different, but the link is the same.

Pros and cons of R Markdown sites

So now you know how to build and update our Markdown sites. And before we move on to the next tool, I just want to highlight some good and bad points to take away about using this tool for a course. So some really great things is that the source stays the same. You can use a lot of your existing documents and just plop them right in without having to change much at all. And another really great thing is that you have these built-in themes you can take advantage of to kind of give your site a makeover easily.

A bad thing about our Markdown sites is that as you start to add many different pages, your directory can get really, really full because our Markdown sites do not allow you to organize pages and our Markdown documents into subfolders. So that's just one thing to kind of keep in mind.

Introducing Distill

But with that, let's go ahead and move on to our next tool, which is Distill. So our next stop on Markdown Mountain is a Distill website, and you'll have to install the Distill package before you can use it.

And I just want to give you a quick tour of the Distill website. So let's go ahead and press play here. And the style of a Distill site is actually not very easy to change without CSS, but it looks pretty slick out of the box. So you can think of Distill as being a little bit like the nerdier sibling of an R Markdown site. It's built for much more technical and scientific communication.

So for example, there is a way to list multiple authors and their affiliations. You can also include footers and asides in your Distill pages. And there's this really nice way to display reuse licenses for your educational content. So those are some of the features in a Distill website that come out of the box.

So you can think of Distill as being a little bit like the nerdier sibling of an R Markdown site. It's built for much more technical and scientific communication.

And so now let's build a minimal Distill site of our own. And just like we did with the R Markdown site, we're going to use the Build tab to knit some files that are in our project directory. And once we do that, it's going to create a folder, again, called underscore site that's going to house our HTML files.

Here is what our minimal Distill site is going to look like. And just to point out, we can also add, we can have a description, we can have those multiple authors, we can still retain that drop down menu that we also had in R Markdown sites.

So let's look at some of these files a little bit more closely, starting with the index page. Again, this is going to be our homepage in a Distill website. And any existing R Markdown document that you have will do. There's just one addition we need to make inside of this file. And that is that in the YAML of the index file, we need to be able to add this line site, Distill, Distill website. And it's also nice to include a title and a short description, but not necessary.

And then we also have an underscore site YAML file. This is still going to be our site configuration. So this should also sound a bit familiar. And the YAML navbar keys here are similar to what we used in R Markdown sites with one important change, the output must specify that this is going to be a Distill article.

Adding a blog to a Distill site

And there's one more thing I need to tell you about Distill websites. You can make part of your Distill website into a blog, which looks like this. So essentially, you can have a single page made up of clickable posts. And each post itself is its own page, and it doesn't need to be built into the navigation bar the way that other parts of the R Markdown sites need to be or like Distill sites need to be. And this can be useful in a classroom setting, just if you want to post different things like announcements, and kind of a running list sort of way.

So in order to create a blog-like page, we first need to create what's called a listing page. And this is an R Markdown document whose only job is to have a title and then a listing YAML key and value. And we're going to call our listing page schedule. And then we have to remember to link this listing page to the navigation bar within site YAML. And once we've done that, then we're ready to make some blog posts.

So the most straightforward way to create a post is to run the code distill create post, and then within the parentheses, you put the title of your post. And this is automatically going to create a new folder called posts with a subdirectory for your post. And it will also trigger a little window to open with your R Markdown file ready for you to edit. You can rinse and repeat this process, creating as many new posts as you'd like.

So let's go ahead and just look inside one of those post files. On the left here, you can see what I mean when I said that it creates a little subdirectory for your post underneath the posts folder. And all of this is created for you. So you don't really have to worry too much about remembering the order here. But if we look inside of the post itself, we see that the YAML is already automatically populated for us with the information that we need. We can edit it if we need to, like change the date or the title.

And the only downside here is that once we're done creating our post, we have to remember to knit this post individually. If you don't knit it on its own, then it won't show up on your listing page. So once we've created all of our posts, we can then remember to build our website one last time so that the listing page will be updated with any posts that we've created.

And here, for example, is what our very minimal blog listing page looks like. So on the left, you see what the listing page is, and then you can click on to any of those individual links to see what the post looks like.

And just as before, once we're ready to share, we can use our old drag and drop method. So we'll take the underscore site folder and drag that in to Netlify, just as we did with our Markdown sites.

Distill pros and cons

So with that, we've covered two of our Markdown tools, and there's just a couple points I want to highlight about Distill before we move on to the next tool. Really nice things about Distill are that you have these really great design features out of the box. You have two content flavors. You can have a regular page, but you can also have this blog-like page, which kind of just lets you show some more chronological content.

One bad thing about Distill, it's just pretty annoying, I guess, to have to remember to knit each individual post one by one, if you would like to take advantage of the blog feature. But the good thing there, at least, is that you don't have to do anything manual to make sure that your posts get on that listing page we created.

Introducing Bookdown

Okay, so now for the rest of the tools, Allison will be our guide for our Ascent Markdown Mountain, and we have two more tools to go. Thank you, Jessica. So I'm going to describe Bookdown now, which is another R package that you need to install before being able to use it.

And as the package name suggests, Bookdown is a way to build books with R Markdown, and you can use it to build an online book with a table of contents, chapters, in fact, as many chapters as you want, and lots of bells and whistles that we won't be able to cover today. But they're all actually covered in the Bookdown book, which you can see here, and it also happens to be a Bookdown book itself.

So you can see that we have a website here that looks a little bit different than the R Markdown and Distill sites that Desiree just showed us. Instead of having that top navigation bar that allowed us to navigate and find the different pages on our site, now we have this table of contents over here in this kind of left sidebar. So when I click on that little hamburger menu, I can see my table of contents going up and down, and I can scroll it. It's a very long table of contents, but you can see that I have a lot of materials in here, and I can click around to any of these, and you can see that the right pane shows me the content of that page as I click around.

So here in a Bookdown book, each of these chapters is actually an R Markdown file, and when I click on it, I'm able to see the content, but I can still access the entire table of contents here. And you can imagine that if you had this many documents in an R Markdown or a Distill site, you would have had to build them usually manually into some kind of top navigation bar, and you just don't have that much real estate going across the top as you do with this kind of layout. So that's one of the reasons that Bookdown is really popular for educators.

Bookdown also comes with search built in, so you're able to search the entire book. So this is also another nice feature that allows you to leverage your content.

So here's an example of a much shorter Bookdown book that I built to show you for a demonstration. So we can give you a quick tour of the files that go into it. So this book has three labs from a course I taught on data visualization. The first one is about Nathan's hot dog eating contest. The second one is the one that Desiree just showed you at the MoMA Museum tour. And the third one was a lesson teaching about colors with ggplot using data about children's production of animal sounds.

So the files in this book project here are on the left. So you can see that I have a few R Markdown files, I have a YAML file, it's an R project, I have some folders, and I have a very important folder called underscore book. Now Desiree, do you happen to remember what the output folder was for R Markdown and Distill Sites? Yes, I do. It was underscore site. Yes. So with a Bookdown book, now our book is in underscore book.

So when I have all of these files that you see over here in the left pane, when I have all those in a directory for an R project, and I mouse over to my build tab, and I click on that build book icon, it creates a new folder called underscore book, and that's where my book now lives locally.

Bookdown file structure

So I'm going to show you inside some of those files now. So let's take a look first at index.rmv. So Desiree described this as the homepage for your other R Markdown sites, and it's actually the homepage also for Bookdown. It also happens to turn into your first chapter.

So if you take a look inside, it looks pretty familiar. There's YAML at the top. We have a title, a subtitle, an author. We also have two new YAML keys on the bottom, and these are critical for building a Bookdown book. They are site and output. So both of those are necessary for building an HTML book like the one we're building now. And then the rest of this file, everything underneath the YAML, can be a regular R Markdown file. It just also happens to turn into chapter one.

So like with our other sites, we also have a separate file, too. So in the R Markdown and the sites that Desiree demonstrated, you had underscore site.yaml file. And in Bookdown, it's an underscore bookdown.yaml file. And this file works in concert with the index.rmv file to guide how all of our chapters fit together.

So I'm going to recommend that your underscore bookdown.yaml file is pretty sparse. The main key that I recommend using for this YAML file is new session, and I recommend that you set it to true. This means that each of your R Markdown chapters is knit in a separate session. This will make your life easier and will make it easier for you to troubleshoot when you're knitting your book, building your book. Any of the errors that you see will be a lot easier to debug if each of the chapters is totally independent.

You might notice that my chapter files here on the left are now named with numbers as prefixes. So I have 01 hot dogs, 02 moma, and 03 meow. You can use the bookdown.yaml file to instead list the order of your R Markdown chapters. So before, it was using the numbered chapters to determine the order that the book got built. You can also take away those numbers from the names of the files and use the bookdown.yaml to determine the order of the chapters as they are presented to you. So that's another way that you can use this underscore bookdown.yaml file.

And the chapters themselves, I have three of them here in addition to the index.rmd. Those are each separate R Markdown files, but they're with one major change. And that is that each of these chapters has to begin with a level one markdown header. So here you see hashtag momamuseumtour. Each of these chapters has to start with that. And so that means that none of your chapters in a bookdown book can have its own yaml.

And so this is probably the biggest problem for if you're going to be trying to convert existing material into bookdown. It means that you're going to have to remove the yaml from each individual R Markdown file that will go into a chapter. So each chapter has to start with a level one markdown header and can't have its own yaml. They actually put in the yaml from the index.rmd.

And so this gives you a little bit of an overview of what bookdown is doing. So what you make is you make these separate R Markdown files for each chapter. So here we have index.rmd and then another rmd and another rmd and each of those begins with that level one chapter heading. Those are all your separate R Markdown files. And remember that index.rmd is a special one that also includes a yaml. What bookdown does when you have this new session true in the bookdown yaml is that it emits these R Markdown files in a separate page. So each of those is now independent. But how do we get to the point where we're seeing them all together? Bookdown merges them and gives us the nice interactive online navigable book that we see when we build the book.

Sharing and customizing your bookdown site

So how do we share the book once it's actually written and built? We know our HTML files live in that underscore book folder. So this should seem like old hat to you now. What I would do is go to app.netlify.com forward slash drop and I can drop that underscore book folder into the same spot and that would give me a link. But you might have noticed that some of those random domain names are hard to remember and keep track of. I believe one that Desiree was working with was called Hardcore Goldwasser. It's good for flying under the radar but they're probably not great for learners and they're probably not easy for you to share. So we can update the domain on netlify.com to make the link easier to share with other people.

So in this example, our random domain was Stoic Babbage. So if you go into the Deploys tab on Netlify once you've made your account, you can see that that's my default subdomain and if I click on Options, Edit Site Name, then I can change it. So here I'm going to change it to datavis-book, which amazingly was not taken. So now I have the domain datavis-book.netlify.com and you can see it takes a second but it has already deployed. The new link works right away and now because I have an account with Netlify and I've changed that domain, that's my domain forever. I can keep that and I can always update that as well the way we showed you earlier.

So the best part about Bookdown is that I think it's hard to get lost in a Bookdown book. By default, you think it's going to be long because you have this big table of contents on the left side. So that works in your favor. People are used to being able to scroll up and down vertically in that table of contents and the search functions help as well. And so since you have more real estate in the table of contents vertically, you can also add a lot more content in. So it may be easier when you have longer form content for teaching as opposed to an R Markdown site or a Distill site where you have to kind of manually build up that site navigation.

The hard parts of Bookdown are that if you're converting existing R Markdown files over to this new format, you're going to have to do some work to be able to remove those YAMLs from your individual files and start them all with those level one chapter headers. You may also need to rename your files and you also still don't get to have subfolders. So you're still going to have all your R Markdown files in one directory. And so once you get a certain number of these, it can pretty quickly feel fairly messy.

Introducing Blogdown

So Desiree, we have made it to the summit, which is Blockdown. We have! Yes! Hooray! Hooray indeed.

So Blockdown is a great package for building custom and unique websites with R Markdown, but it is not for the faint of heart. It is also probably not the best choice for you to adopt on complete short notice because there is a lot to learn. But I wanted to make sure that you know about it in case you've already tried the tools that we've just covered. So if you've already tried R Markdown sites, Distill sites, or Bookdown and you're still not quite satisfied with the options and you want something highly customizable, then you may want to look at Blockdown. Or for other folks who have a little bit more time to prep, if you're looking at a fall or a winter quarter class for next year, you could think about making a website using Blockdown.

So what is Blockdown? It's an R package that helps you build a website using a generator called Hugo. And the package itself lets you use the RStudio IDE to build your site and to use R Markdown content to make your site.

So one of the best and worst things about Hugo is that you now have access to over 100 Hugo themes to choose from. So you can get really creative with Hugo. So you may have felt like when you were looking at Bookdown sites or Distill or R Markdown sites, you've probably seen a lot of sites that look just like those. And there's some benefits to that. I don't think there's anything wrong with using a default site. But a lot of people want to go a little bit further and they have specialized needs that require specialized solutions. But it's also easy to get very overwhelmed by the choices of Hugo themes.

For my own course websites and when I teach, my favorite theme to use is the Hugo academic theme, because it is very well documented and it's very flexible also. The theme also has built-in search, which is really nice. So here is the documentation theme for academic. It's a demonstration site. You can see that I have a little search button up at the top. And you can see that there's all kinds of different content in here. And it's important to remember with Hugo sites, when you look at a demonstration site, it's trying to show you everything. It's not necessarily showing you the best way to lay out everything.

So I built a demonstration site for this webinar using the Hugo academic theme and porting over my existing content from the course I taught on data visualization, where I had that R Markdown site that Desiree actually showed at the very beginning. So I converted all of that content over to BlogDown to show you what's possible. So here is my BlogDown site, and you can access it at share-blogdown.netlify.com, and you can see I have my nice built-in search. I have this top nav bar, and you can see I have some nice features, like being able to link to my RStudio Cloud, perhaps, or my Piazza, GitHub. You can put all those links in one place. You can also see that I have some interesting kind of ways to lay out content that are a little bit more varied than what we had at our fingertips with R Markdown, Distill, and BookDown sites.

Here I've also used blog posts to lay out a schedule, and this was inspired by Meneh Chetankaya-Randell's course website, so showing you each of the labs stacked on top of each other. So here, click on Schedule Lab, the content for that lab. You can also see, of course, a section for the syllabus, and finally, some instructors with pictures, links, all of the things. There's also a resources section here that shows a different kind of layout where you can share different materials with users, just another different option that's available with the Hugo Academic theme.

So here, if you remember, I showed you this schedule, and if I clicked on this Lab02, the MoMA Museum Tour, that's actually the lab that Desiree started with initially. So let me show you what that looks like. You would go to that page, and you would see these two here, Lab, and what each of those goes to is actually, the lab goes to an R Markdown site. So this is housed within my blog down site, but I didn't have to change anything about that file. I literally just copied and pasted it over into a directory in my blog down site. And then I also used ShurEngine slides to make my presentation slides in R Markdown. So you can see that I also copied and pasted those directly from my R Markdown site and directory in my blog down site.

And then this allows me to take advantage of one of the best benefits of using blog down for teaching, which is that when I use the add-in to build my site, so I use the blog down add-in serve site, it creates a folder called underscore public, and that's the website that I see, but what it also does under the hood for me is it builds any other kind of R Markdown content that I have. So I can house my other R Markdown HTML documents in here, as well as my ShurEngine slides. I can do it all, and I can build it all with one button, which is really nice.

So I can house my other R Markdown HTML documents in here, as well as my ShurEngine slides. I can do it all, and I can build it all with one button, which is really nice.

So just a quick tour of some of the files in a blog down project. The content folder is probably the place that you'll want to dig into the most. Your primary R Markdown files will live here. You can also use plain Markdown files. YAML does depend on the theme that you choose, though, so this means that you'll need to change any existing YAML to adapt to your theme, and this is also how you can kind of get locked into a theme. So once you choose a theme in blog down, it's tough to switch. Sometimes I also stash and build other R Markdown documents in the static folder, and if you go to the repository associated with my demo site, you can see how I did that to deploy my R Markdown labs and my ShurEngine slides. So that's just a taste of blog down to give you a flavor for the things that are possible.

Pros and cons of Blogdown

So the good parts of blog down is that you can finally now have subfolders. You can have a content folder organization that might help you if you have a lot of different things like data, assignments, labs, slides. You can also knit anything, so you can have different output formats are possible. Blog down also builds on top of book down, so any of the features that are present in the book down HTML format are also possible in blog down.

The bad things, in my experience, are Hugo. Hugo is a new dependency that we've added. All the other options that we've discussed so far, our Markdown sites, Distill, and Bookdown only had an R package that they depended on, but now when you work with blog down, you are depending on installing Hugo, which is a language that does have different versions. It requires updates. There's a bit of maintenance involved. There's also a more complex directory structure, so with being able to have subfolders, you also gain more complexity as well. So I wouldn't necessarily recommend this for short notice, but I do think it's a nice longer term solution.

Some general blog down advice. I do not recommend that you update Hugo during your course if you're using blog down. I also do not recommend that you update your Hugo theme during your course, and I also just generally recommend don't update anything during your course based on personal experience.

Sharing your Blogdown site with Netlify

So how do you share your blog down site? The way you would do that is by, let's see, play, is by taking that public folder and dragging and dropping that into the app.netlify.com forward slash drop. You can see that it's thinking, thinking, thinking, and I get a very nice random domain name, Nostalgic Brahmgutta, so that would probably be tough for me to remember. I could use the trick that we showed earlier to change that custom domain name to something more memorable.

Here's a shortcut that you can use as well. So if you go to that repository that I made, the share-blogdown repository, I created a little button called a deploy to Netlify button. Now this works if you're logged into GitHub, so if you're already using GitHub for version control, if you click on that deploy to Netlify button, you can see that what it does is it allows you to take the same site that I'm showing you in my repository. You can then link it up to your Netlify account. So here Desiree's showing, logging into her existing Netlify account, existing GitHub account, GitHub account, all right, thank you. And it creates a new repository in her GitHub with the exact same files that I had, and it automatically deploys it to Netlify with all the same settings that I had created. So now Desiree has her own copy of my exact same site with one button. She clicked on the deploy to Netlify button in my repository, her site deploy is in progress.

It takes a little while for Hugo to build the site, so insert Jeopardy music here while it's going. There we go. Stoic Snyder is now live, so she can click on that. So that's the exact same site that I just showed you, but now it's based off source files in her GitHub repository deployed to her own URL in Netlify, Stoic Snyder, and then she can change that, she can edit the files, and she can employ continuous deployment with Netlify, which is by connecting your GitHub account and using GitHub to store your source files, you can connect that to Netlify so that every time you make a change and you push to GitHub, the website can automatically update. So this is how I would really recommend, if you want to use BlogDown, it's one of the great benefits without needing to worry too much about remembering to update your site.

So this is how I would really recommend, if you want to use BlogDown, it's one of the great benefits without needing to worry too much about remembering to update your site.

So if you're familiar with Git and GitHub for version control, and you'd like to take a foray into BlogDown, I recommend that. We also listed some more resources here at our GitHub repository for this talk, it's at rstudio-education, it's called Sharing Short Notice. If you look in the GitHub issues there as well, I've made a list of a bunch of different educational websites, course websites, using the different tools, so I've tagged them whether they used BlogDown or Markdown, BookDown, et cetera, so you can see links to the source deployed version and to the repository, so you can see the source files as well.

So thank you for joining us today, we hope we've left you with some ideas that you can use now and hopefully later, and we hope we've left you with visions of awesome course websites that you can make in the future dancing in your heads, so we're happy to take some questions now.

Q&A

Hi, Peter, will you have explanations for how to use iframes to incorporate learner exercises? That is a very good question, Desiree, I believe that you are the world's expert in using iframes to incorporate learner exercises into static HTML websites.

Yeah, so I have a blog post that kind of walks you through how to do that. It's a little bit involved, not terribly, but it does involve kind of using a little bit of JavaScript and some CSS, but in the blog post, so you can go to my blog, it's desiree.rbind.io, and anyway, that post will kind of walk you through the little lines of JavaScript and CSS that you need to get up and running, and that's something that I've tried using in R Markdown sites, I haven't yet tried incorporating LearnR windows, for example, in Shringen slides or anything like that, but it should work in R Markdown Distill blog down as well.

So I would point you to the blog post there, if you want to get started with that.

I'm putting the link in there, I think if I can see it, I think that's how I send to all. Okay, I think I might have responded to that, okay, so sorry everyone, we're also learning a new tech stack today, so, go to webinar, see, so teaching question, oh, Desiree, you know the answer to this one, how do you make these great videos, such a simple way to show the code process without live coding?

Yeah, so the videos, we used the app CAP, K-A-P, and it just works really, really nice, it gives you the option of outputting either as an MP4 file, or as a GIF, so you have those two options, and actually, out of those two options, I really recommend that you use an MP4 file, because those are much smaller files than GIFs, and it won't weigh down your site as much, and then you can just embed those into any R Markdown file using a video tag.

And I think one other thing that you did, Desiree, was you also made sure that your cursor, like in the accessibility settings of your computer, you made your cursor quite large for doing those videos? Right, yeah, that was within my operating system, I just ramped up the size of my cursor, which is really great, and then within the app CAP, there's a preference setting where you can click show, make my clicks visible, or something like that, and so that's what highlights any time that you click, so that's also really nice for tutorial videos.

That's a really good question, too, that we can work up with screenshots, and with videos, we can work up a blog post for our application, our studio.com blog, to show how to make those kinds of videos, because I do really like them.

Editing generated HTML and output directories

Someone has a question about, suppose I want to modify an HTML, the generated HTML file, and keep these changes when I knit later. Is it possible to do so? Not really. I think my general answer is, all of the output directories that we showed you here today, every time you rebuild your site, they're going to get overwritten every time.

So if you wanted to have some HTML that you wanted to carry through, you can actually use raw HTML in your RMD source files, and have them translate into the generated HTML file, but in general, I wouldn't recommend editing any of the output directories that we showed. So like for our markdown or distil site, that underscore site folder, bookdown, that underscore book folder, and for blogdown, it was the public folder. I would never recommend editing by hand any of those files, because any time you want to update your content, those are going to get rewritten for you.

Is that accurate, according to what you think, Desiree, also? Absolutely, yeah. Don't touch anything in those folders, because it will mostly be a waste of your time. As soon as you knit, it will all wash away.

But yeah, putting raw HTML into the RMarkdown file itself, that works just great, and actually I do that a lot. That works a lot. Yeah.

As soon as you knit, it will all wash away.

Let's see. I actually do not know the question, can we interface RMD files with Jupyter Notebook? I do not know the answer to that, but that's a really good question that we can follow up on community with. We'll chase down the answer to that. I also don't know the answer, yeah.

Netlify vs. GitHub Pages

Let's see. I think I've worked through the questions, and Curtis, did we answer this one? Do you prefer to host the site on Netlify for any specific reason? Or are there any advantages over GitHub? Oh, I don't see that question at all. Thank you.

Desiree, do you want to offer first, or do you want me to? I'll just answer the first part, which I guess Netlify, because of this drag and drop feature, makes it really, really nice. I think GitHub can sometimes be intimidating. It was for me when I first started. So being able to deploy a website without having to understand GitHub or Git is a really nice win, especially if you're doing stuff on short notice. So you can answer the rest, Allison.

Yeah. I think for myself, I use GitHub frequently for education purposes, and so I will say that I switch back and forth. Sometimes I deploy sites via Netlify. Sometimes I use GitHub Pages. It largely depends for me on the kind of project I'm working on and what kind of link I want to be able to link out to and how much I'm updating it. So I tend to defer to Netlify mostly because I have a lot of sites there and it's a nicer interface for me, and the majority of my sites are blogged down, and blogged down has a nice feature where, or Hugo has a nice feature that's actually, Netlify can build Hugo sites for you.

So when you serve your site locally in RStudio, what you're essentially doing is knitting all of your source files into HTML or markdown files, and then Netlify can build your site for you. So it's nice because I'm able to outsource that, and that also allows me to be able to use GitHub throughout my workflow a little bit easier with blogged down. But with the other options, I think I go back and forth. I do tend to use Netlify more, but I wouldn't say it's a completely strong preference.

So, Desiree, you seem like you can see more questions than I can. Yeah. I think I must be able to. I only see three. Okay. Here, yeah, this is very... Here's another question. I created index.rmd, but the tab build site does not appear. What do I have to do? Restart RStudio. So sometimes it might not yet detect all the files in there for it to identify that it needs to show you that build book or build site button. So restart RStudio, open that RProj file again, and you should see that populate.

What does signing up to Netlify using a version control account... Why does signing up to Netlify using a version control account make your life easier? Makes your life easier if you use GitHub already. If you don't use GitHub already, then it may not make much of a difference to you. But the reason why I say that is because you can keep your files that are already in GitHub and have Netlify connect to those. So whenever you make a change locally on your computer to your website, you build your site locally, you can see it, you push to GitHub, and then that's all you have to remember to do is you just have to push it to GitHub, and you don't have to do any extra step to actually deploy or publish your site.

So the way we showed you today in this webinar was a very manual way. It's not a bad way, but it's a very manual way of dragging and dropping physically that folder into Netlify to both deploy it the first time and to update it. And so that could wear on you after a bit if you're updating frequently. If you have a site that's just kind of done and you want to share it, then that's not really a big deal. But if you're updating and maybe adding materials every couple days or every week, you may want to think about starting to use version control. But we didn't want to necessarily depend on that for this workshop because we wanted to make sure that we optimized for being able to share on short notice, which for me does not involve GitHub. Agreed.

Using a university server instead of Netlify

Okay, here's another question. I actually don't know the answer to this one. It is, what if I would prefer not to use Netlify but a university server to store my material? Oh, yeah. You can do that as well. I did that. All you really need to know is know the output directory, right, Desiree? As long as you can drag and drop or place that somewhere, then you've got a hosted website.

Yeah. As soon as I guess, yeah, as soon as you have those HTML files in some place, then you can use whatever server you want following the instructions of whatever that server uses. But that's why it's really nice to know where the site actually is because it's your source files are in your project folder, but knowing where the actual website lives in a directory is nice because that's the only folder that you need to be able to share. Yes.

Okay. There are quite a few other questions here. Let's see. If you wouldn't mind, just to be done on the hour, maybe we could transition some of the questions to RStudio community or maybe an article on the education website, website's blog. Yeah. I don't think I've ever seen this many questions. So there's definitely a lot of interest and a lot of curiosity. So I'll be sure to get those to you as quickly as possible.

Closing remarks

Sounds good. So thank you for the webinar. I would like to say to the audience, you know, a few people reported some audio and visual issues yet, but it's not a problem. We recorded the webinar and we'll post it to the resources, rstudio.resources.com backslash webinars, as well as email everyone who registered for the webinar. So everyone will be able to see the recording as well as I just posted on RStudio community discussion thread to continue the discussion. And I've been collecting a lot of links that you mentioned as well. So people will be able to see some of those resources you referred to as well.

Great. Awesome. Yeah. I'd love to give you an opportunity to kind of tie up and then it's right on the hour for when people are looking to leave the webinar. Okay. Great. Well, I will go back in the slides so everybody can see here's where the repository is. So github.com, rstudio-education, sharing-short-notice. So this is where our slides actually are. So if you want to go there, you can see our slides, our slide files, all the videos, all the images from this talk are in there.

And then if you go to the GitHub issues there in that repository as well, you'll see some more examples where I've linked to the source code and deployed versions of websites so you can hopefully get inspired. Yeah. There are a lot of great ideas there. And we hope that this has been useful for you and inspires you to try some websites on your own if you've been intimidated by that previously. And we hope that this makes building course websites on short notice a little less painful. Thanks everyone. Thank you.

And we hope that this makes building course websites on short notice a little less painful.