Making Websites with R Markdown

---
name: blogdown-title
background-image: url(img/ada_lovelace_cropped.png)
background-size: cover
class: inverse

# Meet blogdown

### .fancy[Making Websites in R Markdown]

---

## So what is blogdown?*

- [R Markdown](https://rmarkdown.rstudio.com) <img src="https://www.rstudio.com/wp-content/uploads/2015/12/RStudio_Hex_rmarkdown.png" width="10%" align="right" />

- (relatively) simple syntax for writing documents
    
    - the simpler, the more portable (multiple output formats)
    
    - not only convenient (maintenance), but also reproducible
    
    - most features of R Markdown _and_ [**bookdown**](https://bookdown.org) (technical writing)!!

- [Hugo](https://gohugo.io) <img src="https://gohugo.io/img/hugo.png" width="10%" align="right" />

- free, open-source, and easy to install (a single binary)
    
    - lightning fast (generates one page in one millisecond)
    
    - general-purpose (not only for blogs)

???

Pandoc's Markdown: paragraphs, section headings, (un)numbered lists, blockquotes, math expressions, tables, images, footnotes, bibliography/citations, ...

See Chapter 2 of the **bookdown** book for additional Markdown features, such as figure/table captions, cross-references, numbered equations, theorems, ...

---

## Why not WordPress, Tumblr, Medium.com, Blogger.com, etc?*

- No R Markdown support (even math support is often nonexistent or awkward)

- Huge benefits of static websites compared to dynamic websites

- all static files, no PHP or databases, no login/password, work everywhere (even offline)
    
    - typically fast to visit (no computation needed on the server side), and easy to speed up via CDN

???

If all you want to write about is what you had for breakfast today, or how cute your kittens are, there is no need to use blogdown. If there is anything related to R, statistical computing, and/or graphics, blogdown will be much more convenient.

---
class: inverse, middle, center

# .fancy[Build a site for [Ada Lovelace](https://en.wikipedia.org/wiki/Ada_Lovelace)]

![](https://lh3.googleusercontent.com/iXmJ9aWblkGDpg-_jpcqaY10KmA8HthjZ7F15U7mJ9PQK6vZEStMlathz1FfQQWV5XeeF-A1tZ0UpDjx3q6vEm2BWZn5k1btVSuBk9ad=s660)

---
name: start-here
class: inverse, middle

1. Make a [repo on GitHub](https://happygitwithr.com/new-github-first.html#make-a-repo-on-github-1)

1. Make a [new RStudio project via git clone](https://happygitwithr.com/new-github-first.html#new-rstudio-project-via-git-clone) 
 *File > New Project > Version Control > Git*

1. Run:

```r
library(blogdown)
new_site(theme = "jpescador/hugo-future-imperfect", 
         sample = TRUE, 
         theme_example = TRUE, 
         empty_dirs = TRUE,
         to_yaml = TRUE)
```

]

1. Make a new RStudio project via wizard 
 *File > New Project > New Directory*

1. Scroll down to select: 
 <img src="https://discourse-cdn-sjc2.com/standard10/uploads/gohugo/original/2X/c/c2d3414c64e766d814100b32063948e604298a70.png" width="4%"> *Website using blogdown*

]

???

if an exampleSite exists, it will be in themes/<hugo-future-imperfect>/exampleSite

theme_example copies that exampleSite into your project root directory (you can always delete the content later)

sample adds a sample R Markdown blog post (can end up in wrong place though)

empty_dirs keeps some folders that are initially empty but for important reasons I'll tell you about

finally, to_yaml converts all the exampleSite content to YAML instead of TOML files. We'll talk more about the difference, but this saves you time and is helpful to have done automatically for you.

---
name: block1
class: middle, inverse, center

# 🔮

## Gaze into your directory structure

---
name: dir-structure

# 🔐 Directory Structure

```r
.
├── .Rproj.user/
├── ada-blog.Rproj
├── archetypes/ 
├── config.toml
├── content/
├── data/
├── index.Rmd
├── layouts/ 
├── public/
├── resources/
├── static/
├── staticman.yml
└── themes/
```

---
name: hugo-index

# 🔐 Directory Structure

```r
.
├── .Rproj.user/
├── ada-blog.Rproj
├── archetypes/ 
├── config.toml
├── content/
├── data/
*├── index.Rmd # DO NOT TOUCH
├── layouts/ 
├── public/ 
├── resources/
├── static/
├── staticman.yml
└── themes/
```

```yaml
---
site: blogdown:::blogdown_site
---
```

???

index.Rmd does one thing- let's open it up- it is your only R markdown YAML. It specifies your output format as a blogdown site. This is specific to using Hugo via blogdown.

---
name: hugo-public

# 🔐 Directory Structure

```r
.
├── .Rproj.user/
├── ada-blog.Rproj
├── archetypes/ 
├── config.toml
├── content/
├── data/
├── index.Rmd 
├── layouts/ 
*├── public/ # IGNORE
├── resources/
├── static/
├── staticman.yml
└── themes/
```

???

public is where your final rendered site files will go

You can mostly ignore this folder- it re-generates every time we serve our site

---
name: noknit
class: middle, inverse, center

# DON'T 🧶 KNIT!

![](https://media.giphy.com/media/Vg6vGMxVs9Sve/giphy.gif)

---
name: serve

# 🛎

# .fancy[Serve site!]

Mouse up to "Addins" ➡️ "Serve site"

![](img/addin-serve-site.png)

---
class: center, inverse, top

# 🦚 Success?

???

What are we seeing here? Everything that is the public folder.

---
class: middle, inverse, center

---
name: earlydeploy
class: middle, inverse, center

# 📣

---
template: earlydeploy

## Go to [Netlify.com](https://www.netlify.com/) & Log in

---
template: earlydeploy

## Drag & drop the `public/` folder to [deploy](https://bookdown.org/yihui/blogdown/netlify.html)

---
class: middle, inverse, center

---
name: yourturn
class: middle, inverse

.left-column[
 
 
 
 
<img src="img/Ada_Lovelace_color.svg" width="75%" style="display: block; margin: auto;" />

]

---
name: yourturn-1
template: yourturn

Ideas:

+ Where are the `.md` files for the .bright[blog posts]? .fancy[(i.e., "Creating A New Theme")]
+ Where is the `.jpg` file you see in the .bright[hex image] stored? What about the featured images for each blog post?
+ Where is the `.md` file you see under .bright[About]? .fancy[(i.e., "Hugo is a static site engine written in Go.")]
+ Where are the `.md` files you see under .bright[Itemized]? .fancy[(i.e., fancy apps 1-4)]

]

---
name: outline
class: middle, inverse

# .fancy[Outline]

1. ~~Gaze into your directory structure~~ [🔑](#block1) [🏆](#yourturn-1)

1. Edit the `config.toml` [🔑](#block2) [🏆](#yourturn-2)

1. Edit the `exampleSite` content [🔑](#block3) [🏆](#yourturn-3)

1. Add new content [🔑](#block4) [🏆](#yourturn-4)

1. Deploy [🔑](#block5)  [🏆](#yourturn-5)

---
name: block2
class: middle, inverse, center

# 🏡

## Edit the configuration file

---

# Edit `config.toml`

```r
*baseurl = "/"
languageCode = "en-us"
*title = "Ada Lovelace"
theme = "hugo-future-imperfect"
preserveTaxonomyNames = true
paginate = 3
disqusShortname = "shortname"
googleAnalytics = ""
pluralizeListTitles = false
# Set the followings to true as part of your site SEO
enableRobotsTXT = true
canonifyURLs = true
*ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]
*relativeURLS = true
```

- `<title>Ada Lovelace</title>`

- `ignoreFiles`: copy and paste this from your R console when you first served your site

- *.bright[Very important!]* Setting `relativeURLS` is critical for ☁️ setup

???

The first thing I do with any new Hugo theme is make sure the baseurl is just a forward slash. That will always work. This theme has that already, but some don't

Do not change theme here- but it refers to the theme folder you want.

You could have multiple Hugo themes in your themes/ directory.

So the theme name should match the name of the folder that holds the theme you want to use.

---
class: middle, inverse, center

## 🆕 A full `public` folder

---

# Back to `config.toml`

```r
baseurl = "/" 
languageCode = "en-us"
title = "Ada Lovelace" 
theme = "hugo-future-imperfect"
preserveTaxonomyNames = true
paginate = 3
disqusShortname = "shortname"
googleAnalytics = ""
pluralizeListTitles = false
# Set the followings to true as part of your site SEO
enableRobotsTXT = true
canonifyURLs = true
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]
relativeURLS = true 
*enableEmoji = true

[params]
  # Sets the meta tag description
* description          = "Ada's blog"
  # Sets the navbarTitle that appears in the top left of the navigation bar
* navbarTitle          = "Ada Lovelace"
  # Sets where "View More Posts" links
  viewMorePostLink     = "/blog/"
```

???

There are some standard parameters in hugo config.toml files- just because it isn't in the site's example config doesn't mean you can use them!

---
name: livereload

# 🛎

# .fancy[Click save!]

Through the magic of .fancy[.bright[LiveReload]], 
you don't need to serve your site again.

???

What are we seeing here? Everything that is the public folder.

---

# Add image

Mouse over to `static/img/main/` and see `logo.jpg`? We can replace that file, or make new file. I'll replace mine with [this picture](https://raw.githubusercontent.com/apreshill/ada-blog/hugo-theme-future-imperfect/static/img/main/ada_square.jpg).

```r
[params.intro]
* header    = "Ada Lovelace"
* paragraph = "A fine place to share my thoughts"
* about     = ""

# This appears at the top of the sidebar above params.intro.header.
  # A width of less than 100px is recommended from a design perspective.
  [params.intro.pic]
*   src       = "/img/main/ada_square.jpg"
    # Sets Image to be a cirlce
    circle    = false
    # Sets Image to be Future Imperfect's hexagon
    imperfect = true
    width     = ""
*   alt       = "Ada portrait from Wikipedia"
```

???

In the Hugo framework, static things are images, CSS, JavaScript, etc.

So you can assume that any image files are expected to be somewhere in the static directory.

Here, it looks like the exampleSite used the path static/img/main. So mouse over there and see if you see logo.jpg.

You could save over that image, or you can add another image and update the file name in the config file.

When Hugo builds your site, all assets inside your static directory are copied over as-is.

---
class: center, inverse, top

# 🦚 Success?

---
name: yourturn-2
template: yourturn

Ideas:

+ Update your `[[menu.main]]` text, Font Awesome icons (or remove!), or switch weights (the order).
+ Set up your `[social]` media icons.
+ Change the `highlightjs` theme.
+ Switch some of the "Optional Params"- see what they do.

.bright[.fancy[Stretch:]] All possible Hugo configuration variables are [listed here](https://gohugo.io/getting-started/configuration/)- try some (like `enableEmoji = TRUE`)!

]

---
name: block3
class: middle, inverse, center

# 🎩

## Edit the `exampleSite` content

---
name: hugo-themes

# 🔐 Directory Structure

???

themes is where all the Hugo theme files go.

This determines the look and layout of your site, as well as the bells and whistles that each individual Hugo theme developer employs. It also may leave out some Hugo bells and whistles that you DO want.

IT ALL DEPENDS ON YOUR THEME

You also never touch this folder!

So how do you edit a Hugo theme if you are not to touch anything in this folder?

---
class: middle, inverse

# 🔑 Overriding vs editing

> *When you use a theme cloned from its git repository, do not edit the theme’s files directly. Instead, theme customization in Hugo is a matter of overriding the templates made available to you in a theme. This provides the added flexibility of tweaking a theme to meet your needs while staying current with a theme’s upstream.*

---
class: middle, inverse

# 🕳 `empty_dirs = TRUE`

```r
.
├── .Rproj.user/
├── ada-blog.Rproj
*├── archetypes/
├── config.toml
├── content/
├── data/
├── index.Rmd
*├── layouts/
├── public/
├── resources/
├── static/
├── staticman.yml
└── themes/
```

???

This is why we kept the empty directories when we started our site.

I believe having these here will help you when you do want to edit your theme, as a gentle reminder that you are never to touch the themes folder!

---

# Themes

Look in `/themes/hugo-future-imperfect/`. Notice now the folder structure here *mirrors* your Hugo directory structure.

---

# Override files in...

```r
.
├── .Rproj.user/
├── ada-blog.Rproj
*├── archetypes/
├── config.toml
├── content/
├── data/
├── index.Rmd
*├── layouts/
├── public/
├── resources/
*├── static/
├── staticman.yml
└── themes/
```
]

---
name: hugo-archetypes

# Hugo Archetypes

```r
.
├── .Rproj.user/
├── ada-blog.Rproj
├── archetypes/ 
*|   └──  blog.md
*|   └──  default.md
*|   └──  itemized.md
├── config.toml
├── content/
├── data/
├── index.Rmd
├── layouts/
├── public/
├── resources/
├── static/ 
├── staticman.yml
└── themes/
```

???

You can create new content files in Hugo using the hugo new command. By default, Hugo will create new content files with at least date, title (inferred from the file name), and draft = true. This saves time and promotes consistency for sites using multiple content types.

---
name: hugo-blog

# The blog archetype

.pull-left[
`themes/hugo-future-imperfect/archetypes/blog.md`
```js
+++
author = ""
categories = [""]
date = ""
description = ""
featured = ""
featuredalt = ""
featuredpath = ""
linktitle = ""
title = ""
type = "post" 
+++
```

]

.pull-right[
`content/blog/goisforlovers.md`
```js
---
author: Unknown Author
categories:
- Go
date: "2014-04-02"
description: ""
featured: pic02.jpg
featuredalt: Pic 2
featuredpath: date
linktitle: ""
title: (Hu)go Template Primer
type: post
---
```
]

---

# TOML vs. YAML

- TOML is like YAML, but not 
- blocks wrapped by `+++` vs `---` 
- Your `config.toml` file doesn't show this explicitly but it is there!
- key-value pairs are separated by a `=` vs `:` 
- YAML uses indentation with one or more spaces to describe nested collections

This is why we used `new_site(to_yaml = TRUE)`!

If you end up with TOML in your content, try (after backing up your files):

```r
hugo_convert(to = "YAML", unsafe = TRUE)
```

https://learnxinyminutes.com/docs/yaml/

https://learnxinyminutes.com/docs/toml/
]

---
class: inverse, middle, center

# Archetypes 🔄 Layouts
---
name: hugo-layouts

# Hugo Layouts

```r
.
├── .Rproj.user/
├── ada-blog.Rproj
├── archetypes/
*|   └──  blog.md
*|   └──  default.md
*|   └──  itemized.md
├── config.toml
├── content/
├── data/
├── index.Rmd
*├── layouts/
├── public/
├── resources/
├── static/ 
├── staticman.yml
└── themes/
```

???

Stores templates in the form of .html files that specify how views of your content will be rendered into a static website.

---
name: yourturn-3
template: yourturn

.right-column[
# .fancy[05:00 minutes]
### Edit some `exampleSite` content, save, and let "LiveReload" preview your changes.

1. Edit the .bright[About] page.

1. Edit a .bright[Blog] post.

1. .bright[Challenge!] In `content/blog/` there is the sample `.Rmd` blog post titled .fancy["Hello R Markdown"]. Can you find it on the site? Can you spot the problem? .fancy[.bright[hint: it was to do with a YAML parameter that tells Hugo which layout to use]]

]

---
name: block4
class: middle, inverse, center

# 📯

## Add new content

---
class: middle, center

---

# 🆕 Hugo Page Bundles

```r
library(usethis)
edit_r_profile()
*options(blogdown.new_bundle = TRUE)
```

---

# 🌱 Page Bundles

```r
content/
*├── about
│   ├── index.md
├── posts
*│   ├── my-post
│   │   ├── content1.md
│   │   ├── content2.md
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   └── index.md
*│   └── my-other-post
│       └── index.md
```

Allowed bundle resources:
+ Page and non-page (like images, pdf, etc.) types

---
class: middle, inverse, center

---
class: middle, inverse, center

---
name: global-options

# 🌍 Other global options

```r
library(usethis)
edit_r_profile()
options(blogdown.author = "Ada Lovelace",
        blogdown.ext = ".Rmd",
        blogdown.subdir = "blog",
        blogdown.yaml.empty = TRUE,
        blogdown.new_bundle = TRUE,
        blogdown.title_case = TRUE)
```

[More global options](https://bookdown.org/yihui/blogdown/more-global-options.html)
]

---
name: yourturn-4
template: yourturn

1. .fancy[Optional:] Use `usethis::edit_r_profile` to add some **blogdown** global options.
  + Don't forget the blank line at the end, and restart your R session, serve your site again.

1. Use the "New Post" addin to create new content. 
 + Try adding a new post to .bright[Blog] (include a featured image in your bundle!)
 + Try adding a new project to .bright[Itemized]

]

---
name:workflow

# Workflow*

- Open your website project, click the "Serve Site" addin
    
- Revise old pages/posts, or click the "New Post" addin
    
- Write and save (take a look at the automatic preview)
    
- Push everything to Github

---

# Theme examples

- [Mitchell O'Hara-Wild](https://blog.mitchelloharawild.com/)

- [Isabella Velásquez](https://ivelasq.rbind.io/)

- [Cool But Useless](https://coolbutuseless.github.io/)

---

# Blogdown resources

- [Blogdown demo site](https://blogdown-demo.rbind.io)
- [Blogdown book](https://bookdown.org/yihui/blogdown/)
- [I did a blog post on it](https://alison.rbind.io/post/up-and-running-with-blogdown/)
- [Also did a workshop](https://alison.rbind.io/talk/blogdown-meetup/)
- [Yihui's slides from RStudio Conf](https://slides.yihui.name/2018-blogdown-rstudio-conf-Yihui-Xie.html)

---
template: earlydeploy

# Update on Netlify

---
publishing

cloud rstudio server pro very important

Make sure you are in a RStudio project dedicated to the blog.
    Add relativeURLS=true to config.toml
    Develop as normal using blogdown::serve_site()
    When you're ready to deploy, use the Build Pane's Build Website command.
    Click Publish from the built preview, and select "Publish finished website only"

---
name: yourturn-5
template: yourturn

1. ☁️ | 💻
  + Use RStudio Connect

1. 💻 + 
 + Add a `.gitignore`
 + Push your changes to GitHub
 + On Netlify.com, New Site from Git > pick your repo

]
---

📰

Extra Extra!

Want to change the landing page? You need to do two things:

1. add an `_index.md` file to `content/` (not in a subfolder)
1. update the `index.html` layout

Let's try it!

---

Update your theme if you want:

```r
blogdown::install_theme("gcushen/hugo-academic", 
                        theme_example = TRUE, 
*                       update_config = TRUE)
```