Sharing on Short Notice

layout: true

<a class="footer-link" href="https://rstudio-education.github.io/sharing-short-notice/">rstd.io/sharing</a>

---

class: title-slide, center, bottom

# Sharing on Short Notice

## How to Get Your Teaching Materials Online with R Markdown

### Alison Hill &#183; Desirée De Leon

???

Welcome to the webinar on sharing on short notice

Where we'll show you how to get your teaching materials online with R Markdown.

---
name: clouds
class: center, middle
background-image: url(images/Clouds.jpg)
background-size: cover

---
template: clouds

## .big-text[Hello.]

???

So hello- we're so happy you could join us today.

---
name: clouds2
background-image: url(images/Clouds2.jpg)
background-size: cover

---
template: clouds2
class: middle, center

.pull-left[
### Alison Hill

[<i class="fab  fa-github "></i> @apreshill](https://github.com/apreshill)  
[<i class="fab  fa-twitter "></i> @apreshill](https://twitter.com/apreshill)

]

???

My name is Alison Hill, and I'm a data scientist and professional educator at RStudio.

.pull-right[
### Desirée De Leon

[<i class="fab  fa-github "></i> @dcossyleon](https://github.com/dcossyleon)  
[<i class="fab  fa-twitter "></i> @dcossyle](https://twitter.com/dcossyle)

]

???

And I'm Desirée De Leon. I interned with Alison last summer at RStudio on the education team.

---
template: clouds2
class: middle, center

.pull-left[
### Alison Hill

<img src="https://media.giphy.com/media/WTEdeICMGkw91sHEy1/giphy.gif" style="width: 82.07%; display: block; margin: 1 auto;">
[<i class="fab  fa-github "></i> @apreshill](https://github.com/apreshill)  
[<i class="fab  fa-twitter "></i> @apreshill](https://twitter.com/apreshill)

]

.pull-right[
### Desirée De Leon

<img src="https://media.giphy.com/media/hoqxB6HRhWtySSjO2S/giphy.gif">
[<i class="fab  fa-github "></i> @dcossyleon](https://github.com/dcossyleon)  
[<i class="fab  fa-twitter "></i> @dcossyle](https://twitter.com/dcossyle)

]

???

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

---
class: freight-slide, center, middle, inverse

# .shadow-text[We ship a lot of websites.]

???

I am 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.

Here are just a few of them.

---
class: freight-slide, center, middle, inverse

# .shadow-text[We ship a lot of websites.]

http://bit.ly/giraffe-stats

https://education.rstudio.com/

https://bookdown.org/yihui/blogdown/

https://stat545.com/

https://conf20-intro-ml.netlify.com/

https://summer-of-blogdown.netlify.com/

https://apreshill.github.io/data-vis-labs-2018/

???

If you type the short link on the bottom right of this slide into your browser right now, you'll be able to follow along.

All of these links are clickable from the slides.

Each site was built using R Markdown, with different tools chosen depending on what we needed.

---
template: clouds

# Who are you?

???

So that's us. Who are you?

---
class: middle, center

<div class="flex" style="margin: 0 1em;">
  <div class="column">
    <h3> You're an educator <h3>
    <img src="images/rawpixel/educator.jpg" style="width: 100%;">
  </div>
  
???

Here's who we think you are...

You're an educator
  
--

???

You have R Markdown files for teaching...

---
class: middle, center

<div class="flex" style="margin: 0 1em;">
  <div class="column">
    <h3> You're an educator </h3>
    <img src="images/rawpixel/educator.jpg" style="width: 100%;">
  </div>
  
  <div class="column"style="margin: 0 1em;">
    <h3> You've got lots of .Rmds </h3>
    <img src="images/rmd-buddy-help.jpg" style="">
  </div>
  
???

But they're stuck on your computer, and you need to share them easily others with out filling up their inboxes.
  
--
  <div class="column" style="margin: 0 1em;">
    <h3> Your new classroom </h3>
    <img src="images/internet.jpg"  style="">
  </div>
</div>

???

And--- you probably have a new classroom space that looks like this-- so sharing needs to be done 100% online

---
class: center
background-image: url("images/rawpixel/lesson-time.jpg")
background-size: contain
background-color: #f6f6f6

## You might feel like this right now.

???

And you might feel like this right now.

Everything seems to need your attention,

but you cannot do everything.

---
class: middle, center

# Sharing on **short notice**

???

With that in mind, today we'll give you a quick tour of the...

---
class: middle, center
background-image: url("images/short1.jpg")
background-size: cover

# Sharing on **short notice**

???

**R Markdown tools** you can use to get your course materials...

---
class: middle, center
background-image: url("images/short2.jpg")
background-size: cover

# Sharing on **short notice**

???

**online**...

---
class: middle, center
background-image: url("images/short3.jpg")
background-size: cover

# Sharing on **short notice**

???

on **short notice**.

---
class: middle, center
background-image: url("images/rawpixel/inflation.jpg")
background-size: contain
background-color: #EBEAE6

???

So we'll show you how to build a course website to help you teach and reach learners using R Markdown, and friends.

Our goal is to give you a quick boost to help you get your site UP off the ground...

---
class: inverse, center
background-image: url("images/rawpixel/blue-balloon.jpg")
background-size: cover

# This

???

with a shareable link so that you can get on with your teaching...

---
class: top center
background-image: url("images/rawpixel/balloon-ouch.jpg")
background-position: bottom center
background-size: 40%

# Not this

???

and hopefully avoid crashing in the process.

---
class: center, top

## Why make a course website?

???

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.

That makes it more **reproducible** -- for myself and others.

But it is also a way to make me more resilient --
if I'm organized AND online I can be more nimble when changes need to happen.

The side benefit of all this is that it is ALSO more **shareable**, so it makes it easier for learners too b/c they see what I see.

Because we'll be building websites with R Markdown, we'll start by talking about a single file. Desiree - you're up!

---
template: clouds

# What does an .Rmd look like?

???

Jumping right in, what *does* an R Markdown file look like?

---
class: center, middle

???

Here is an r project folder for a lab.

---
class: center middle

???
Inside that folder, you'll notice an RProj file. Opening that file in RStudio takes us...

---
background-image: url(images/screenshots/Single-rmd.png)
background-size: contain
class: middle, center

???

**here**, where we can see our single R Markdown file. This one is for a lab for visualizing data from the Museum of Modern Art.

Let's quickly walk through some of the key parts of this file.

---
background-image: url(images/screenshots/Single-rmd0.png)
background-size: contain
class: middle, center

???

It starts with metadata, written in YAML, which is a list of keys on the left and their values on the right.

---
class: middle, center
background-image: url(images/screenshots/Single-rmd1.png)
background-size: contain

???

The first key you see is the TITLE, which is `Lab 02: MoMA Museum Tour`.

---
class: middle, center
background-image: url(images/screenshots/Single-rmd2.png)
background-size: contain

???

The last YAML section is all about output. Here the output is an html document.

---
class: middle, center
background-image: url(images/screenshots/Single-rmd3.png)
background-size: contain

???

Beneath that, we can add options to our html document -- for example, a table of contents, with the key TOC set to TRUE.

---
class: middle, center
background-image: url(images/screenshots/Single-rmd4.png)
background-size: contain

???

So that's the metadata, but the real meat in your R Markdown file 
is text written in markdown...

---
class: middle, center
background-image: url(images/screenshots/Single-rmd5.png)
background-size: contain

???

and your code, written in R.

So these 3 things: metadata, text, and code make up an R Markdown document.

---
class: top center

???

ALISON says:

Of course, Desiree, the real magic happens, when you click on the Knit icon, and see your file turned into HTML.

So, here's what that looks like:

- We knit
- We can watch in this bottom pane as our R Markdown document gets processed.
- And voila! -- we see our rendered HTML file. 
- We can choose to open this up in a real browser window.
- And then just test a few things out.

---
class: middle center
background-image: url(images/screenshots/Single-knit1.png)
background-size: contain

???

Here is what we knit.

???

Using the `THEME:` key in our YAML, we changed our font and colors.

???

And we have this nice table of contents floating off to the side...

???

But this is still local and stuck on my computer.

A *link* would make it easier to share.

---
template: clouds
class: center, middle

# How do we start .emphasis[sharing]?

???

So how do we start sharing?

---
background-image: url("images/Server.jpg")
background-size: 80%
background-position: bottom
class: center, top

# How do we start .emphasis[sharing]?

???

We need a **web server**...

--
<img src="https://github.com/nolistic.png" style="
  position: absolute; 
  width: 10%; 
  top: 140px;
  right: 60px;
  border-radius: 50%;
">

???

which is basically a big computer in the clouds

hat/tip to Heather Nolis for that analogy.

--
<img src="images/Netlify.png" style="
  position: absolute; 
  width: 23%; 
  top: 218px;
  right: 301px;
">

???

And for this webinar, we'll use servers provided by Netlify.

---
class: top center

# How do we start .emphasis[sharing]?

.pull-left[
## Go here:
#### [app.netlify.com/drop](https://app.netlify.com/drop)
]

.pull-right[
<img src= "https://summer-of-blogdown.netlify.com/assets/netlify-drop.png" style="width: 85%;">
]

???

We are going to drag and drop our project folder into Netlify and put our webpage online.

So, Alison-- let's do our first drag and drop!

---
class: center, middle

???

ALISON says:

So, I open up my browser, and go to app.netlify.com/drop --

and  drag n drop the folder in.

A few seconds later, Netlify has  auto-generated a silly-name link and deployed our page -- this link is where our Lab02 page now lives,  and you can share your page with whomever you choose --

BOTH: hooray!

---
class: center, middle
background-image: url(images/Clouds.jpg)
background-size: cover

# What just happened?

???

What just happened?

---
background-image: url(images/what-happened/single-doc/Slide1.jpeg)
class: middle center
background-size: contain

???

**We started with an R Markdown file named index**

We knit this to convert to an internet-ready HTML file

It looked great, but still only lived locally in our R Project folder

So then we dragged and dropped our folder

Netlify deployed our page

and generated a link! Woohoo!

---
background-image: url(images/what-happened/single-doc/Slide2.jpeg)
class: middle center
background-size: contain

???

We started with an R Markdown file named index

**We knit this to convert to an internet-ready HTML file**

It looked great, but still only lived locally in our R Project folder

So then we dragged and dropped our folder

Netlify deployed our page

and generated a link! Woohoo!

---
background-image: url(images/what-happened/single-doc/Slide3.jpeg)
class: middle center
background-size: contain

???

We started with an R Markdown file named index

We knit this to convert to an internet-ready HTML file

**It looked great, but still only lived locally in our R Project folder**

So then we dragged and dropped our folder

Netlify deployed our page

and generated a link! Woohoo!

---
background-image: url(images/what-happened/single-doc/Slide4.jpeg)
class: middle center
background-size: contain

???

We started with an R Markdown file named index

We knit this to convert to an internet-ready HTML file

It looked great, but still only lived locally in our R Project folder

**So then we dragged and dropped our folder**

Netlify deployed our page

and generated a link! Woohoo!

---
background-image: url(images/what-happened/single-doc/Slide5.jpeg)
class: middle center
background-size: contain

???

We started with an R Markdown file named index

We knit this to convert to an internet-ready HTML file

It looked great, but still only lived locally in our R Project folder

So then we dragged and dropped our folder

**Netlify deployed our page**

and generated a link! Woohoo!

---
background-image: url(images/what-happened/single-doc/Slide6.jpeg)
class: middle center
background-size: contain

???

We started with an R Markdown file named index

We knit this to convert to an internet-ready HTML file

It looked great, but still only lived locally in our R Project folder

So then we dragged and dropped our folder

Netlify deployed our page

**and generated a link! Woohoo!**

---
background-image: url(images/rawpixel/single-balloon.jpg)
background-size: contain
background-position: left
class: middle, center

.pull-right[
### But that is just one .Rmd file...
]

???

But that is just one R Markdown file...

---
background-image: url(images/rawpixel/bunch-balloons.jpg)
background-size: contain
background-position: right
class: middle, center

.pull-left[
### We want to share many .Rmd files!
]

???

We want to share many R Markdown files!

---
background-image: url(images/mtsalsa0.jpg)
background-position: bottom center
background-size: contain
class: top, center

## So where are we going?

???

So we're going to hike Markdown mountain today...

---
background-image: url(images/mtsalsa.jpg)
background-position: bottom center
background-size: contain
class: top, center

## So where are we going?

???

And our goal for the rest of this webinar is to show you 4 R Markdown tools that are for turning a *COLLECTION* of RMDs into a web*site*.

---
name: default_site
class:  top, center
background-image: url(images/mtsalsa-rmd.jpg)
background-size: contain
background-position: center, bottom

# `install.packages("rmarkdown")`

???

So let's begin with an R Markdown site.

To make one, you only need the `rmarkdown` package installed, which is already done for you if you use RStudio.

---
template: clouds2
class: center, top

<https://apreshill.github.io/data-vis-labs-2018>

???

Here is an R Markdown site for a course about data visualization. Actually, the MoMA lab 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 the labs.

The biggest addition here is this top navigation bar...

???

which allows us to link to other webpages...

---
template: clouds2
class: center middle

<https://apreshill.github.io/data-vis-labs-2018>

???

including ones made with R Markdown, like this page with slides and readings...
    
---
template: clouds2
class: center middle

<https://apreshill.github.io/data-vis-labs-2018>

???

Or other websites, like this one here which goes to a learning management system.

---
name: build1

## Build your site

.pull-left[

```r
.
*├── rstats101.Rproj
├── _site.yml
├── index.Rmd 
├── schedule.Rmd 
├── lab01.Rmd
└── lab02.Rmd
```
]

.pull-right[
<img src="images/rproj.png" width="325" />

]
???

So let's build a minimal R Markdown site of our own.

Imagine that this box on the left is the list of files that are inside of our R Project folder.

---
name: build5

## Build your site

.left-column[

```r
.
├── rstats101.Rproj
├── _site.yml 
├── index.Rmd 
├── schedule.Rmd 
├── lab01.Rmd 
└── lab02.Rmd 
```
]

.right-column[
<img src="images/screenshots/build-site.png" style="margin-top: -28px;">
]

???

To knit all these pages in our R Markdown site, you can mouse over to the Build Tab in RStudio and then click "Build Website".

---
name: build6

## Build your site

.left-column[

```r
.
├── rstats101.Rproj
*├── _site/
├── _site.yml 
├── index.Rmd 
├── schedule.Rmd 
├── lab01.Rmd 
└── lab02.Rmd 
```
]

.right-column[
<img src="images/screenshots/build-site.png" style="margin-top: -28px;">
]

???

Now you can see that it created a new folder called `_site`- that is where our html files live.

---
template: clouds2
class: center top

![](images/screenshots/RMD-site.png)

???

Here is the site we just built. We have a navbar, a theme -- and even a dropdown menu!

Let's look under the hood at some of these files.

---
background-image: url("images/rawpixel/bunch-balloons-rmd1.jpg")
background-position: right
background-size: contain

## .hidden[Inside the `index.Rmd`]

.left-column[

```r
.
├── rstats101.Rproj
├── _site/ 
├── _site.yml
*├── index.Rmd
├── schedule.Rmd 
├── lab01.Rmd
└── lab02.Rmd
```
]

???

Let's start with index.Rmd.

Index is a special file name in any website- because it is the homepage.

So if each of our R Markdown files in our site was a hot air balloon here, `index` would be the first you would see.

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside the `index.Rmd`

.left-column[

```r
.
├── rstats101.Rproj
├── _site/ 
├── _site.yml
*├── index.Rmd
├── schedule.Rmd 
├── lab01.Rmd
└── lab02.Rmd
```
]

.right-column[
```
---
title: "rstats 101"
---

# Welcome to the course!

This is the course website...
```
]

???

If we take a peek inside index.Rmd, we don't see anything special-

in fact, you can take *any* existing R Markdown document that you already have, rename it `index`, and turn it into your site's homepage.

---
background-image: url("images/rawpixel/bunch-balloons-rmd2.jpg")
background-position: right
background-size: contain

## .hidden[Inside the `_site.yml`]

.left-column[

```r
.
├── rstats101.Rproj
├── _site/ 
*├── _site.yml
├── index.Rmd 
├── schedule.Rmd 
├── lab01.Rmd
└── lab02.Rmd
```
]

???

The `_site.yml` is new.

This is the file that ties all the pages together.

It is called the site configuration file, written in YAML.

Let's take a look inside...

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside the `_site.yml`

.left-column1[

```yaml
navbar:
  title: rstats101
  left:
  - text: Schedule
    href: schedule.html
  - text: Labs
    menu:
    - text: Lab 1
      href: lab01.html
    - text: Lab 2
      href: lab02.html
output:
  html_document:
    theme: flatly
```
]

.right-column1[
<img src="images/screenshots/RMD-site.png" width="782" />
]

???

The first thing you may notice is this is a YAML file, so there are no fences, but it is a list of keys and values.

The first key is `navbar:`, and this is how you build your site's navigation.

--
<img src="images/screenshots/RMD-site-title.png" style="
  position: absolute;
  width: 64%;
  top: 135px;
  right: 6px;">
  
???
there is key for the title...

???

Whether we want links on the left or right...

???

And if we want links listed in a dropdown menu, we can do that too...

???

For all the pages you link to in your navbar, the `href:` needs to point to an .html file, even though the source may be R Markdown.

Finally, we set up a theme that applies to the navbar and all pages.

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside the `_site.yml`

.left-column1[

```r
navbar:
  title: rstats101
  left:
  - text: Schedule
*   href: schedule.html
  - text: Labs
    menu:
    - text: Lab 1
*     href: lab01.html
    - text: Lab 2
*     href: lab02.html
output:
  html_document:
    theme: flatly
```
]

.right-column1[
<img src="images/screenshots/RMD-site.png" width="782" />
]

???

For all the pages you link to in your navbar, the `href:` needs to point to an .html file, even though the source may be R Markdown.
---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside the `_site.yml`

.left-column1[

```r
navbar:
  title: rstats101
  left:
  - text: Schedule
    href: schedule.html
  - text: Labs
    menu:
    - text: Lab 1
      href: lab01.html
    - text: Lab 2
      href: lab02.html
output:
  html_document:
*   theme: flatly
```
]

.right-column1[
<img src="images/screenshots/RMD-site.png" width="782" />
]

???

Finally, we set up a theme that applies to the navbar and all pages.

---
background-image: url("images/rawpixel/bunch-balloons-rmd3.jpg")
background-position: right
background-size: contain

## .hidden[Other `.Rmd`s]
.left-column[

```r
.
├── rstats101.Rproj
├── _site/ 
├── _site.yml 
├── index.Rmd 
*├── schedule.Rmd
*├── lab01.Rmd
*└── lab02.Rmd
```
]

???

As for the other R Markdown pages, there is nothing special about them.

As long as you link to a page in `_site.yml`, you can take any existing R Markdown file and turn it into a page within a website.

---
class: middle, center
background-image: url(images/Clouds2.jpg)
background-size: cover

![](images/screenshots/Lab1.png)

???

quiz Alison, what do you think the YAML for this lab page looks like??

---
class: middle, center
background-image: url(images/Clouds2.jpg)
background-size: cover

![](images/screenshots/Lab1-annotated.png)

???

Answer:

toc
toc_float
and code download

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside a page

.left-column[

```r
.
├── rstats101.Rproj
├── _site/ 
├── _site.yml 
├── index.Rmd 
├── schedule.Rmd 
*├── lab01.Rmd
└── lab02.Rmd
```
]

.right-column[
```yaml
---
output:
  html_document:
    toc: true
    toc_float: true
    code_download: true
---
```

```
# Lab One

In our first week together, 
we'll cover the syllabus 
and how to use Zoom.

```
]

???

Good job, Alison!

That is exactly what we see. You can set the YAML for each page if you want.

If you wanted these output options on every page in your site, we could have added these to the `_site.yml` instead.

---
background-image: url("images/rawpixel/bunch-balloons-rmd4.jpg")
background-position: right
background-size: contain

## Sharing your site

.left-column[

```r
.
├── rstats101.Rproj
*├── _site/
├── _site.yml 
├── index.Rmd 
├── schedule.Rmd 
├── lab01.Rmd 
└── lab02.Rmd
```
]

???

Okay, we're finally, ready to share our R Markdown site -- we'll do this the same way as before. All of our HTML, website-ready pages are stored in the _site/ folder. So This this is the only folder, we need to ddrag and drop

---
class: middle, center
background-image: url(images/Clouds2.jpg)
background-size: cover

???

And we will drop that folder back into netlify to make our site.

---
class: left
background-image: url(images/Clouds2.jpg)
background-size: cover

# But...

.left-column[
![](https://media.giphy.com/media/3orif5e8QhgoL9TvmU/giphy.gif)
]

.right-column[

]

???

But you may have noticed...

unclaimed sites are deleted after 24 hours. We have to create an account with Netlify to keep our site online permanently.

So let's go back to Netlify and do that.

---
background-image: url(images/Clouds2.jpg)
background-size: cover
class: middle center

???

ALISON

If you already use GitHub or BitBucket, then I recommend you use that to sign in becuase you're workflow will be smoother if your accounts are connected. But for today, I'm just going to sign up with email...

Once you've signed up, you'll see you have an account dashboard. And your silly-named link is now here to stay.

---
template: clouds

# What if I make a change?

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## What if I make a change?

.left-column1[

.right-column1[
<img src="images/screenshots/build-site.png" style="margin-top: -28px;">
]

???

Let's say I want to use the united theme, instead of flatly.

I change that in my site yaml, re-build my site, then...

---
background-image: url(images/Clouds2.jpg)
background-size: cover
class: center, middle

???

ALISON

Once we've re-built our site wiith the changes we want. We'll go back to our _site/ folder.

In netlify, we can make sure we are in the "deploy" tab of our dashboard -- and there's a spot specifically for updating. WE can drag and drop again here.

We click on the link--and see our new theme has been applied.

---
template: clouds

# Thoughts on R Markdown Sites

???

You now you know how to build and update R Markdown sites...

---
class: middle
background-image: url(images/rawpixel/balloon-ouch.jpg)
background-position: left
background-size: contain

.pull-right[
### The good

* Source stays same

* Built-in themes

### The bad

* No Subfolders

]

???

Some great thing about R Markdown sites:

You don't have to change much from your original docs. 
You get to use built in themes

One not to great thing is that you can't use subfolders -- which means you can end up with a lot of files in your directory. That can get messy, but that's how it is.

With those points in mind, let's move on to our next tool.

---
name: distill
class:  top, center
background-image: url(images/mtsalsa-distill.jpg)
background-size: contain
background-position: center, bottom

# `install.packages("distill")`

???

Our next stop on Markdown Mountain is Distill, which you'll need to install before you can use it.

---
class: middle, center
template: clouds2

<https://rstudio.github.io/distill/>

???

This is a distill website.

The style is not easy to change without CSS, but it looks pretty slick out-of-the-box.

Think of distill as the nerdier sibling of an R Markdown site- it is built for technical and scientific communication.

For example...

---
class: middle, center
template: clouds2

<https://rstudio.github.io/distill/>
<img src="images/screenshots/distill-authors.png" style="margin-top: -28px;">

???

There's a way to list multiple authors and their affiliations...

---
class: middle, center
template: clouds2

<https://rstudio.github.io/distill/>
<img src="images/screenshots/distill-aside.png" style="margin-top: -28px;">

???

You can include footers and asides...

---
class: middle, center
template: clouds2

<https://rstudio.github.io/distill/>
<img src="images/screenshots/distill-reuse.png" style="margin-top: -28px;">

???

And you can display reuse licenses for your educational content.

---
## Build your site

.left-column[

```r
.
├── DataViz.Rproj
*├── _site/
├── _site.yml 
├── index.Rmd 
├── lab01.Rmd
├── lab02.Rmd 
└── project.Rmd

```
]

.right-column[
<img src="images/screenshots/build-distill.png" style="margin-top: -28px;">
]

???

So now let's build a minimal Distill site of our own.

Just like we did with the R Markdown site, we use the build tab to knit all our files at once.

This creates a `_site` folder for our HTML files.

---
background-image: url(images/Clouds2.jpg)
background-size: cover

![](images/screenshots/min-distill.png)
--

--
<img src="images/screenshots/min-distill1.png" style="
  position: absolute; 
  width: 100%; 
  top: 0px;
  left: 0px;
">

???

Quick things to notice -- let's look inside.

---
class: middle
background-image: url("images/rawpixel/bunch-balloons-rmd1.jpg")
background-position: right
background-size: contain

.left-column[

```r
.
├── DataViz.Rproj
├── _site/
├── _site.yml 
*├── index.Rmd
├── lab01.Rmd
├── lab02.Rmd 
└── project.Rmd 
```
]

???

The index page in a distill site will work just the same as in an R Markdown site.

It will be the site's home page.

Any existing R Markdown document you have will do.

But there is one addition we make inside of this file.

---
background-image: url(images/Clouds2.jpg)
background-size: cover
## Inside the `index.Rmd`

.left-column[

```r
.
├── DataViz.Rproj
├── _site/
├── _site.yml 
*├── index.Rmd
├── lab01.Rmd
├── lab02.Rmd 
└── project.Rmd 
```
]

.right-column[

```r
---
title: Intro to Data Visualization
description: Spring 2020 Course Website
author:
  - name: Alison Hill
    affiliation: RStudio
  - name: Desirée De Leon
    affiliation: Teacup Giraffes, Inc.
*site: distill::distill_website
---

# Welcome to the course!
```
]

???

`site: distill::distill_website` should be added to the YAML.

Including a title and short description is nice too.

[*note*: `site: distill::website` is only necessary if you wanna make the blog later]

---
background-image: url(images/rawpixel/bunch-balloons-rmd2.jpg)
background-position: right
background-size: contain

## .hidden[Inside the `_site.yml`]

.left-column[

```r
.
├── DataViz.Rproj
├── _site/
*├── _site.yml
├── index.Rmd
├── lab01.Rmd
├── lab02.Rmd 
└── project.Rmd 
```

]

???

Next we move on to the `_site.yml` page. 
It's still for site configuration. This should sound a bit familiar...

---
background-image: url(images/Clouds2.jpg)
background-size: cover
## Inside the `_site.yml`

.left-column[

```r
.
├── DataViz.Rproj
├── _site/
*├── _site.yml
├── index.Rmd
├── lab01.Rmd
├── lab02.Rmd 
└── project.Rmd 
```

]

.right-column[

```r
title: DataViz 
navbar:
  right:
    - text: Labs
      menu:
      - text: Lab 1
        href: lab01.html
      - text: Lab 2
        href: lab02.html
    - text: Project
      href: project.html
*output: distill::distill_article
```
]

???

The YAML navbar keys here are all similar to what we used in an R Markdown site, with one important change:

The output **must** specify that this is a Distill article.

---
background-image: url(images/Whisper.jpg)
background-size: contain

<div class="word-bubble" style="
  position: absolute; 
  text-align: center;
  width: 50%; 
  top: 100px;
  left: 310px;
  font-size: 1.3em;
"> Alas, I have kept one important thing <br> from you about Distill websites. </div>

???

And.. there is one more thing I need to tell you.

---
template: clouds
class: center middle

#  A Distill Blog

???

Part of your Distill site can be in a blog format!

---
class: middle, center
background-image: url(images/Clouds2.jpg)
background-size: cover

???

You can have a single page made up of clickable posts, like this.
Each post is itself its own page, and it doesn't need to be built into the navigation bar.

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Add a listing page

.left-column[

```r
.
├── DataViz101.Rproj
├── _site/
├── _site.yml
├── index.Rmd
├── lab1.Rmd 
├── lab2.Rmd 
├── project.Rmd 
*└── schedule.Rmd

```

]

.right-column[
```
---
title: Schedule
listing: posts
---
```
]

???

Instead, we create a listing page -- an R Markdown document whose only job is to have a title and a listing YAML key and value.

We'll call our "schedule".

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Update the `_site.yml`

.left-column[

```r
.
├── DataViz101.Rproj
├── _site/
*├── _site.yml
├── index.Rmd
├── lab1.Rmd 
├── lab2.Rmd 
├── project.Rmd 
└── schedule.Rmd
```

]

.right-column[

```r
title: Data Viz
navbar:
  right:
    - text: Labs
      menu: 
      - text: Lab 1
        href: lab01.html
      - text: Lab 2
        href: lab02.html
    - text: Project
      menu: project.html
*   - text: Schedule
*     menu: schedule.html
output: distill::distill_article
```
]

???

Then, we link our listing page to navigation bar.

Now we are ready to make some posts.

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Create a post

.pull-left[

```r
.
├── DataViz.Rproj
├── _site/
├── _site.yml
├── index.Rmd
├── Project1.Rmd 
├── Project2.Rmd
*└── _posts/
```
]

.pull-right[

```r
distill::create_post("Week1")
```
]

???

In your console, run the `distill::create_post( )` function, and give your post a title in quotes.

This will make a new folder called `posts/`, a sub-directory for your new post, and it will open up a new R Markdown file for you to edit.

You can rinse and repeat -- creating as many new posts as you'd like.

Let's look inside one.

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside a post

.left-column[

```r
_posts/ 
*├── Week1/
* └── Week1.Rmd
├── Week2/
└── Week3/
```
]

.right-column[
```
---
title: Week 1
date: 03-24-2020
output: distill::distill_article
---

During our first week we will 
make our first plots with `ggplot2`.
```
]

???

(You can see on the left what I mean by the sub-directory for your post.)

On the right, we see the YAML of your new post will be automatically populated with the appropriate keys, but you can edit them if you'd like.

Now you can paste in the body content of any existing R Markdown file into your post, **knit**, and you'll be good to go.

Unfortunately, each posts **does** have to be knit individually.

---
## Build once more

.left-column[

```r
.
├── DataViz.Rproj
*├── _site/
├── _site.yml 
├── index.Rmd 
├── lab01.Rmd
├── lab02.Rmd 
└── project.Rmd

```
]

.right-column[
<img src="images/screenshots/build-distill.png" style="margin-top: -28px;">
]

???

Finally, you'll need to build once more, so that the listing page will be updated with the new posts.

---
background-image: url(images/Clouds2.jpg)
background-size: cover
class: middle center

## A minimal "blog" page

![](images/screenshots/distill-min-blog.png)

???

Here's what this "blog page" looks like when it's rendered.

Which means that we're now about done with Distill and...

---
class: center

## Sharing your site

???
and we're ready to share using the ol' drag n drop. 
So, we'll use the `_site` folder just like we did with RMD sites.

---
class: middle
background-image: url(images/rawpixel/balloon-ouch.jpg)
background-position: left
background-size: contain

.pull-right[

### The good

* Nice features out-of-the-box

* 2 content flavors

### The bad

* Knit posts one-by-one (but no manual adding to menus!)

]

???

With that, we've now covered the first two R Markdown tools.

---
name: bookdown
class:  top, center
background-image: url(images/mtsalsa-book.jpg)
background-size: contain
background-position: center, bottom

# `install.packages("bookdown")`

???

Now, Alison will be our guide for the rest of our ascent up markdown mountain.

ALISON:

Thank you Desiree! We'll start with bookdown, which is an additional package that you need to install before using it.

---
background-image: url("images/rawpixel/writing-machine.jpg")
background-size: contain
background-position: right
class: middle

# Online book with...

???

So as the name of the package suggests, bookdown is a way to build books with R Markdown.

You can use it to build an online book with a...

+ Table of contents

???

table of contents

+ Chapters

???

Multiple chapters, in fact as many as you want!

+ Bells & whistles

???

and lots of bells and whistles that we can't cover today.

---
class: middle, center
template: clouds2

<https://bookdown.org/yihui/bookdown/>

???

They are all covered in the bookdown book, which you can see here.

It's also a bookdown book itself!

You can see that instead of using a top navbar, this format gives me a way to navigate the book using a very long but scrollable table of contents in this left sidebar.

Each chapter is an R Markdown file, which when I click on it, shows up in the right pane.

Bookdown also comes with search built-in.

---
template: clouds2

![](images/screenshots/min-bookdown.png)

???

Here is a much shorter bookdown book, which I'll use now to give you a quick tour.

It has 3 labs from a course I taught on data visualization.

---
## Build your book

.left-column1[

```r
.
├── 01-hotdogs.Rmd
├── 02-moma.Rmd
├── 03-meow.Rmd
├── _bookdown.yml
├── dataviz-book.Rproj
├── images/
├── index.Rmd 
*└── _book/
```
]

.right-column1[
<img src="images/screenshots/build-bookdown.png" style="margin-top: -28px;">
]

???

The files in this project are on the left.

To make the book from these files, we click on the build book button in the top right pane.

This creates a new folder called `_book`, which is where our book now lives.

Let's look at some of the other files...

---
background-image: url("images/rawpixel/bunch-balloons-book1.jpg")
background-position: right
background-size: contain

## .hidden[Inside the `index.Rmd`]

.left-column1[

```r
.
├── 01-hotdogs.Rmd
├── 02-moma.Rmd
├── 03-meow.Rmd
├── _bookdown.yml
├── dataviz-book.Rproj
├── images/
*├── index.Rmd
└── _book/ 
```
]

???

The index.Rmd file turns into the first chapter.

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside the `index.Rmd`

.left-column1[

```r
.
├── 01-hotdogs.Rmd
├── 02-moma.Rmd
├── 03-meow.Rmd
├── _bookdown.yml
├── dataviz-book.Rproj
├── images/
*├── index.Rmd
└── _book/ 
```
]

.right-column1[

```yaml
---
title: Principles & Practice of Data Visualization
subtitle: Spring 2020
author: Alison Hill
site: bookdown::bookdown_site
output: bookdown::gitbook
---
# Welcome {-}
```

]

???

If we peek inside, we see some familiar YAML at the top, like a title and author.

We also have 2 new YAML keys: `site` and `output`. Both are necessary for building an HTML book.

Then the rest of that file can be a regular R Markdown file.

---
background-image: url("images/rawpixel/bunch-balloons-book2.jpg")
background-position: right
background-size: contain

## .hidden[Inside the `_bookdown.yml`]

.left-column1[

```r
.
├── 01-hotdogs.Rmd
├── 02-moma.Rmd
├── 03-meow.Rmd
*├── _bookdown.yml
├── dataviz-book.Rproj
├── images/
├── index.Rmd 
└── _book/ 
```
]

???

Like with our other sites, we have a separate yaml file too.

This one is named `_bookdown.yml`, and it works with the index.Rmd file to tie all our chapters together.

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside the `_bookdown.yml`

.left-column1[

```r
.
├── 01-hotdogs.Rmd
├── 02-moma.Rmd
├── 03-meow.Rmd
*├── _bookdown.yml
├── dataviz-book.Rproj
├── images/
├── index.Rmd 
└── _book/
```
]

.right-column1[
```yaml
new_session: true
```
]

???

I recommend using this file to set at least one new key: new session as true.

This makes sure that each chapter is knit in separate R sessions.

You might notice that my chapter files right now are named with numbers as prefixes...

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside the `_bookdown.yml`

.left-column1[

```r
.
├── hotdogs.Rmd
├── moma.Rmd
├── meow.Rmd
*├── _bookdown.yml
├── dataviz-book.Rproj
├── images/
├── index.Rmd 
└── _book/
```
]

.right-column1[
```yaml
rmd_files:
- index.Rmd
- hotdogs.Rmd
- moma.Rmd
- meow.Rmd
new_session: true
```
]

???

If you don't want them numbered, you can use this yaml file to specify the order of the rmd chapters by filename instead.

---
background-image: url("images/rawpixel/bunch-balloons-book3.jpg")
background-position: right
background-size: contain

## Inside the chapters

.left-column1[

```r
.
*├── 01-hotdogs.Rmd
*├── 02-moma.Rmd
*├── 03-meow.Rmd
├── _bookdown.yml 
├── dataviz-book.Rproj
├── images/
├── index.Rmd 
└── _book/ 
```
]

???

The chapters themselves are each separate R markdown files. With one major change...

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Inside one chapter

.left-column1[

```r
.
├── 01-hotdogs.Rmd 
*├── 02-moma.Rmd
├── 03-meow.Rmd 
├── _bookdown.yml 
├── dataviz-book.Rproj
├── images/
├── index.Rmd 
└── _book/ 
```
]

.right-column1[

```
# MoMA Museum Tour

We’ll use data from the Museum of 
Modern Art (MoMA), 
publicly available on GitHub 
and as analyzed by [fivethirtyeight.com](https://fivethirtyeight.com/features/a-nerds-guide-to-the-2229-paintings-at-moma/).
```

]

???

None of the chapters can have a YAML.

This will mean that you'll need to change any individual R Markdown file that you want to convert into chapters in a book.

Each chapter has to start with a level 1 markdown header like "MoMA Museum Tour" here.

---
background-image: url(images/bookdown-km.png)
background-size: contain

---
background-image: url("images/rawpixel/bunch-balloons-book4.jpg")
background-position: right
background-size: contain

## Sharing your book

.left-column1[

```r
.
├── 01-hotdogs.Rmd 
├── 02-moma.Rmd 
├── 03-meow.Rmd 
├── _bookdown.yml 
├── dataviz-book.Rproj
├── images/
├── index.Rmd 
*└── _book/
```
]

???

So, how do we share the book once it's written and built? We know our HTML files live in the _book folder so this should seem like old hat to you now...

---
class: middle center

???

We would drag that folder straight into Netlify to get a link.

---
background-image: url(images/Clouds2.jpg)
background-size: cover

???

But these random domain names are hard to remember and keep track of.

We can update the domain on netlify.com to make the link easier to share.

...

And it really is there- the new link works right away.

---
class: middle
background-image: url(images/rawpixel/balloon-ouch.jpg)
background-position: right
background-size: contain

.pull-left[
### The good

+ Hard to get lost

### The bad

+ Converting

+ (Still) no subfolders

]

???

The best part about bookdown is it is hard to get lost. The TOC and search functions really help, and because we have more real estate in the TOC vertically, you can squeeze a lot more content in.

The hard parts are that to convert existing files over, you may need to rename them and you definitely have to remove the YAMLs. You also still don't get to have subfolders.

---
name: blogdown
class: top, center
background-image: url(images/mtsalsa-blogdown.jpg)
background-size: contain
background-position: center, bottom

# `install.packages("blogdown")`

???

So Desiree- we have made it to the summit- blogdown!

---
background-image: url(images/rawpixel/knight.jpg)
background-size: contain
background-color: #F5ECE0

???

Blogdown is a great package for building custom and unique websites with R Markdown.

But, it is not for the faint of heart.

It also may not be good for you to adopt on short notice, because there is a lot to learn.

But I want you to know about it in case you've already tried the tools we just covered and are still not quite satisfied with the options.

---
class: center, middle, inverse

![](images/hugo.svg)

<https://gohugo.io/>

???

So what is blogdown? It is an R package that helps you build a website using a generator called HUGO.

The package lets you use the RStudio IDE and R Markdown to make your site.

---
class: center, middle
background-image: url(images/rawpixel/so-many.jpg)
background-position: left
background-size: contain

.pull-right[
<https://themes.gohugo.io/>
]

???

One of the best and worst things about Hugo is that there are themes- so you can really get creative.

But you can also easily get overwhelmed by the choices- there are over 100 themes to choose from.

---
class: center, middle
template: clouds2

<https://academic-demo.netlify.com/>

???

For course websites, my favorite theme to use is the Hugo academic theme, because it is well documented and flexible.

This theme also has search built-in, which is nice.

---
class: center, middle
background-image: url(images/Clouds2.jpg)
background-size: cover

<https://share-blogdown.netlify.com/>

???

Here is a hugo academic site I built for this webinar as a demo.

I took my old data visualization course website made with R Markdown that Desiree started with, and converted it to blogdown to show you what is possible.

---
template: clouds2

![](images/screenshots/blogdown-labs.png)

---
template: clouds2

![](images/screenshots/blogdown-lab02.png)

---
template: clouds2

![](images/screenshots/blog-1.png)

---
## Build your site

.left-column1[

```r
.
├── R/
├── config/_default
├── content/
├── data/
├── resources/_gen
├── static/
├── themes/hugo-academic
├── config.toml
├── index.Rmd
├── share-blogdown.Rproj
*└── _public
```

]

.right-column1[

]

---
background-image: url(images/rawpixel/bunch-balloons.jpg)
background-position: right
background-size: contain

## .hidden[Primary content]

.pull-left[

```r
.
├── R/ 
├── config/_default
*├── content/
├── data/
├── resources/_gen
├── static/ 
├── themes/hugo-academic
├── config.toml
├── index.Rmd
├── share-blogdown.Rproj
└── _public 
```

]

???

The content folder is probably the place you'll dig into the most.

Your primary content will live here, in either R Markdown or plain Markdown files. The YAML will depend on your theme.

This means you'll need to change any existing YAML to adapt to your theme.

And this is how you get locked into a theme.

---
background-image: url(images/rawpixel/bunch-balloons.jpg)
background-position: right
background-size: contain

## .hidden[Stash]

.pull-left[

```r
.
*├── R/
├── config/_default
├── content/
├── data/
├── resources/_gen
*├── static/
├── themes/hugo-academic
├── config.toml
├── index.Rmd
├── share-blogdown.Rproj
└── _public 
```

]

???

Sometimes I stash and build other R Markdown documents in the static folder.

You can see how I did that in the demo files with my R Markdown labs and xaringan slides.

---
class: middle
background-image: url(images/rawpixel/blue-balloon-side.jpg)
background-position: left
background-size: contain

.pull-right[
### The good

+ Subfolders!

+ Knit *anything*

+ `bookdown`

### The bad

+ Hugo 😬

+ Complex

+ **not** for short notice

]

---
background-image: url(images/rawpixel/balloon-ouch.jpg)
background-position: left
background-size: contain
class: middle

.pull-right[

## `blogdown` advice

]

.pull-right[

+ Don't update Hugo during your course.

]

.pull-right[

+ Don't update your Hugo theme during your course.

]
--

.pull-right[

+ Seriously, just don't update anything during your course.

]

---
## Share your site

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Here's a shortcut you can use

---
background-image: url(images/Clouds2.jpg)
background-size: cover

## Ideas & resources

+ Continuous deployment

+ More here: https://github.com/rstudio-education/sharing-short-notice

---
background-image: url("images/rawpixel/site-dreams.jpg")
background-size: 80%
background-position: bottom, center
class: center, top
background-color: #FCFEF8

## Thank you

???

Thanks for joining us today. We hope we've left you with some ideas you can use now and later. And we hope we leave you with visions of websites dancing in your heads :)