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 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.
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.
Deploying to Netlify
So how do we start sharing? 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. 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.
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.
Classic R Markdown site
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.
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.
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.
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 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.
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. But with that, let's go ahead and move on to our next tool, which is Distill.
Distill websites
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. 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.
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.
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.
Bookdown
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 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. 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.
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.
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.
Blogdown
So Desiree, we have made it to the summit, which is Blogdown. We have! Yes! Hooray! Hooray indeed. So Blogdown 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 Blogdown. 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 Blogdown.
So what is Blogdown? 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 Blogdown 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 Blogdown site.
And then I also used Xaringan 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 Blogdown site. And then this allows me to take advantage of one of the best benefits of using Blogdown for teaching, which is that when I use the add-in to build my site, so I use the Blogdown 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 Xaringan 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 Blogdown 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 Blogdown, 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 Xaringan slides. So that's just a taste of Blogdown to give you a flavor for the things that are possible.
So the good parts of Blogdown 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. Blogdown also builds on top of Bookdown, so any of the features that are present in the Bookdown HTML format are also possible in Blogdown.
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 Blogdown, 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 Blogdown advice. I do not recommend that you update Hugo during your course if you're using Blogdown. 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.
I also just generally recommend don't update anything during your course based on personal experience.
So how do you share your Blogdown 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 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.
