blogdown and You

# blogdown and You
## An Introduction to Creating Websites Using R
### Emilie Campos
### UCLA Biostatistics Computing Club
### 2020-04-09 (Updated 2020-03-31) Slides available at <a href="http://bit.ly/bsa-blogdown-2020">http://bit.ly/bsa-blogdown-2020</a>.

---

<style>

.remark-slide-number {
  position: inherit;
}

.remark-slide-number .progress-bar-container {
  position: absolute;
  bottom: 0;
  height: 6px;
  display: block;
  left: 0;
  right: 0;
}

.remark-slide-number .progress-bar {
  height: 100%;
  background-color: #EB811B;
}

.wrap {
    width: 1225px;
    height: 500px;
    overflow: hidden;
}

iframe {
    width: 142.9% !important;
    height: 142.9% !important;
    -webkit-transform: scale(0.7);
    transform: scale(0.7);
    -webkit-transform-origin: 0 0;
    transform-origin: 0 0;
}

a, a > code {
  text-decoration: none;
}

.inverse {
  background-color: #003B5C;
  text-shadow: none;
}

.title-slide .inverse .remark-slide-content {
  background-color: #FAFAFA;
  border-top: 0px solid #FAFAFA;
}

.remark-slide-content {
  background-color: #FAFAFA;
  border-top: 80px solid #FAFAFA;
  font-size: 20px;
  font-weight: 300;
  line-height: 1.5;
  padding: 1em 2em 1em 2em
}

h1 {
  font-weight: normal;
  margin-top: -50px;
  margin-left: -00px;
  color: #1A292C;
}

.title-slide {
  background-color: #FAFAFA;
  border-top: 80px solid #FAFAFA;
}

.pull-left {
  float: left;
  width: 49%;
}
.pull-right {
  float: right;
  width: 49%;
}

.caption {
  text-align: center;
  font-size: 1rem;
}

.supp-slide .remark-slide-number {
 display: none;
}
</style>

# A *VERY* brief introduction

There are tons of resources out there which can mean that it's overwhelming.

Your first stop should be the creators' book on `blogdown`: https://bookdown.org/yihui/blogdown/

This presentation will more than loosely follow the tutorial created by one of the creators found at https://alison.rbind.io/post/2017-06-12-up-and-running-with-blogdown/

---

# `blogdown`

An R package for creating websites using RMarkdown and Hugo

![](images/blogdown-package.png)

---

# Get Started

---

# Install `blogdown`

Install the CRAN version:

```r
install.packages("blogdown") 
```

Or use the development version:

```r
if (!requireNamespace("devtools")) install.packages("devtools")
devtools::install_github("rstudio/blogdown")
```

---

# Install Hugo using `blogdown`

```r
blogdown::install_hugo()
# or
library(blogdown) 
install_hugo()
```

Other functions you may want to use:

```r
blogdown::update_hugo() # force an update 
blogdown::hugo_version # check version
```

---

# Create a new R project

- Create a new R Project from the menu `File -> New Project -> New Directory`

- Name your project the same as your site, i.e. "ucla-biostat-computing-club"

- Update R project options [https://bookdown.org/yihui/blogdown/rstudio-ide.html#fig:project-options](https://bookdown.org/yihui/blogdown/rstudio-ide.html#fig:project-options)

---

# Build your site

Themes available: https://bookdown.org/yihui/blogdown/other-themes.html

Take some time to choose a theme because it's somewhat difficult to change

- Default theme

```r
blogdown::new_site() 
```

- Academic theme is super popular

```r
blogdown::new_site(theme = "gcushen/hugo-academic", 
                   theme_example = TRUE, 
                   empty_dirs = TRUE)
```

---

# Hugo Directory Structure

https://gohugo.io/getting-started/directory-structure/

Know your way around:

```r
.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── public
├── static
└── themes
```

(Some of these folders may be missing if you didn't specify to keep empty directories)

---

# Directory names

* Trailing slash will indicate a directory name, e.g., `content/` means a directory named content instead of a file named content.

```r
.
├── archetypes
├── config.toml
*├── content
|   └── posts
├── data
├── layouts
├── public
├── static
└── themes
```

---

# File names

* Leading slash in a path indicates the root directory of the website, e.g., `/static/css/style.css` means the file `static/css/style.css` under the root directory of your website project instead of your operating system.

```r
.
├── archetypes
├── config.toml
├── content 
├── data
├── layouts
├── public
├── static
|   └──  css
*|        └──  style.css
└── themes
```

---

# Overriding vs editing

https://gohugo.io/themes/customizing/

> *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.*

---

# Serve site

- Console

```r
blogdown::serve_site()
```

- or RStudio Addin (*recommended*)

---

# LiveReLoad

https://bookdown.org/yihui/blogdown/a-quick-example.html

1. Edit + save triggers

1. Blocks your console **by design**

1. Don't try to view in your *teeny tiny* RStudio viewer; click: `Show in new window`

---

# Edit your site

---

# Edit your site: To do list

⬜ Add a logo

⬜️ Update the "About" page

⬜️ Enable emojis

⬜️ Change the navigation bar

⬜️ Customize CSS

⬜️ Add awesome icons

⬜️ Hugo homepages

---

# Adding a logo

The logo file belongs in the `/static/` directory:

> *`/static/` stores all the static content for your future website: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is.*
https://gohugo.io/getting-started/directory-structure/

1. Move `01-images` folder to `/static/`

1. Rename folder `images` (so now you have a `static/images/` folder with 2 .png files in it)

1. Update `config.toml` and save

```r
  [params.logo]
*    url = "bsa-logo-hex.png" 
    width = 50
    height = 50
    alt = "Logo"
```

---

# Adding a logo

We saw:

`/themes/<THEME>/static/images/logo.png`

Could be overwritten by:

`/static/images/<bsa-logo-hex.png.png>`

The filename `<bsa-logo-hex.png.png>` could have been anything, because there is a place to specify the url in the `config.toml` file

> *This only works for templates that Hugo “knows about” (i.e., that follow its convention for folder structure and naming). If a theme imports template files in a creatively named directory, Hugo won’t know to look for the local /layouts first.*
https://gohugo.io/themes/customizing/

---

# Edit your site: To do list

✅ Add a logo

⬜️ Update the "About" page

⬜️ Enable emojis

⬜️ Change the navigation bar

⬜️ Customize CSS

⬜️ Add awesome icons

⬜️ Hugo homepages

---

# Updating the "About" page

1. Move `02-about.md` file to `/content/`

1. Delete the existing file `about.md`

1. Rename `02-about.md` --> `about.md`

---

# Updating the "About" page

> *`/content/` stores all content for your website... Each top-level folder in Hugo is considered a content section. For example, if your site has two main sections—blog posts and your about page— you will have 1 directory at `content/post/` and 1 file `content/about.md`.* 
https://gohugo.io/getting-started/directory-structure/

```r
.
├── archetypes
├── config.toml
├── content
*| └── post <<- path: `baseurl/post/` 
*| └── about.md <<- path: `baseurl/about/`
├── data
├── layouts
├── public
├── static
└── themes
```

---

# Edit your site: To do list

✅ Add a logo

✅ Update the "About" page

⬜️ Enable emojis

⬜️ Change the navigation bar

⬜️ Customize CSS

⬜️ Add awesome icons

⬜️ Hugo homepages

---

# Enabling emojis

- Top of your `config.toml` file

- Note the last line 😉

```r
baseurl = "/"
languageCode = "en-us"
*title = "UCLA Biostatistics Computing Club" 
theme = "hugo-lithium-theme"
googleAnalytics = ""
disqusShortname = ""
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]
*enableEmoji = true 
```

- In your "About" page, :heart: should now be ❤️

---

# Enabling emojis

> *Often the default settings are good enough, but the config file can provide highly granular control over how your site is rendered.*
https://gohugo.io/getting-started/configuration/

Go to the **All Variables, TOML** section for the full list

Note that the values nested under `[params]` will populate the `.Site.Params` variable for use in templates (more on this later)

---

# Edit your site: To do list

✅ Add a logo

✅ Update the "About" page

✅ Enable emojis

⬜️ Change the navigation bar

⬜️ Customize CSS

⬜️ Add awesome icons

⬜️ Hugo homepages

---

# Changing the navigation bar

In your `config.toml` file:

```r
[[menu.main]]
    name = "About"
    url = "/about/"
*  weight = 1
[[menu.main]]
    name = "GitHub"
*  url = "https://github.com/UCLA-BSA" 
*  weight = 2
[[menu.main]]
    name = "Biostat Dept."
*  url = "https://www.biostat.ucla.edu/"
*  weight = 3
```

---

# Changing the navigation bar
      
The `[[menu.main]]` in your `config` file is special:

> *A menu entry in a menu template has specific variables and functions to make menu management easier.*
https://gohugo.io/variables/menus/

---

# Edit your site: To do list

✅ Add a logo

✅ Update the "About" page

✅ Enable emojis

✅ Change the navigation bar

⬜️ Customize CSS

⬜️ Add awesome icons

⬜️ Hugo homepages

---

# Customizing CSS

1. In `/static` create a new directory `css`

2. Move `05-bcc.css` file to `/static/css/`

3. Rename `05-bcc.css` --> `bcc.css`

4. In `config.toml`, add last line

```r
[params]
   description = "A website built through Hugo and blogdown."
*  customCSS = ["css/bcc.css"]
```

---

# Edit your site: To do list

✅ Add a logo

✅ Update the "About" page

✅ Enable emojis

✅ Change the navigation bar

✅️ Customize CSS

⬜️ Add awesome icons

⬜️ Hugo homepages

---

# Adding awesome icons

About [Font Awesome](http://fontawesome.io):

> Font Awesome gives you scalable vector icons that can instantly be customized — size, color, drop shadow, and anything that can be done with the power of CSS.

Go [here](http://fontawesome.io/get-started/) to enter your email address and receive a Font Awesome embed code. We'll use mine for demo tonight.

To use them, you need 2 things:

1. the Font Awesome CSS file (where should this go?), and 
1. a script that directs your site to where the fonts can be found (via Font Awesome's Content Delivery Network, or CDN)

---

# Adding awesome icons

You know the drill now- always remove my numbers, `##-`, that are prepended to filename

1. Move `font-awesome.min.css` to `/static/css/`

1. Create a new directory in `layouts/` called `partials`

1. Move other `head_custom.html` and `nav.html` to `/layouts/partials/` 
  - Why? Let's open them up and take a look

Note that you can [use the icons anywhere](http://fontawesome.io/examples/), for example, you could add them to your About page:

`For more information, contact us at <mailto:ejcampos@ucla.edu>.`

For more information, contact us at &nbsp;<mailto:ejcampos@ucla.edu>.

---

# Adding awesome icons

Make changes to these sections in your `config.toml`:

```r
[[menu.main]]
    name = "About"
    url = "/about/"
    weight = 1
[[menu.main]]
    name = "Github"
*   pre = "fa-github"
    url = "https://github.com/UCLA-BSA"
    weight = 2
[[menu.main]]
    name = "Biostat Department"
    url = "https://www.biostat.ucla.edu/"
    weight = 3
    
[params]
    description = "A website built through Hugo and blogdown."
*   customCSS = ["css/bcc.css", "css/font-awesome.min.css"]
```

---

# Edit your site: To do list

✅ Add a logo

✅ Update the "About" page

✅ Enable emojis

✅ Change the navigation bar

✅️ Customize CSS

✅️ Add awesome icons

⬜️ Hugo homepages

---

# Hugo homepages

https://gohugo.io/templates/homepage/

The lookup order for the homepage template is as follows:

```
/layouts/index.html
/layouts/_default/list.html
/themes/<THEME>/layouts/index.html
/themes/<THEME>/layouts/_default/list.html
```

---

# Hugo homepages

- Where should we move the file `index.html`?

- Move `index.html` --> `/layouts/`

---

# Hugo homepages

Edit the `config.toml` file

```r
[params]
{{  description = "The UCLA Biostatistics Computing Club is an organization 
    to provide hands-on learning at a variety of skill levels."}}
   customCSS = ["css/bcc.css", "css/font-awesome.min.css"] 
```

---

# Edit your site: To do list

✅ Add a logo

✅ Update the "About" page

✅ Enable emojis

✅ Change the navigation bar

✅️ Customize CSS

✅️ Add awesome icons

✅️ Hugo homepages

---

# Uh oh, we lost our posts

Get them back by adding a tab for them in the `config.toml` file

```toml
[[menu.main]]
    name = "Biostat Department"
    url = "https://www.biostat.ucla.edu/"
    weight = 3
    
*[[menu.main]]
*   name = "Posts"
*   pre = "fa-bullhorn"
*   url = "/post/"
*   weight = 4
```

---

# Deploy your site

---

# Deploy your site

* The publishing directory is by default `/public/`.

* Each time you serve your site locally, Hugo will generate your website to `/public/`.

* You can upload everything under `/public/` to any web server that can serve static websites, and your website will be up and running.

* You could also use a *continuous deployment service*. When linked to a git repository, any git push triggers an automatic fresh deployment. (This is what I do)

https://gohugo.io/hosting-and-deployment/hosting-on-netlify/

* If using continuous deloyment, you'll need a .gitignore file, and you will need to add `public/` to your list of files for git to ignore

---

# How to git

- From the start https://apreshill.rbind.io/post/up-and-running-with-blogdown/

- At the end http://happygitwithr.com/existing-github-last.html

---

# Netlify deploy settings

![](images/netlify-settings.png)

---

# Netlify site name

This was the original site name: `shepherd-brushes-37154`

On [Netlify](https://www.netlify.com), go into `General -> Site details -> Site information -> Change site name` and update

![](images/netlify-site-name.png)

---

# Further Questions

See any of Yihui or Alison's work first! Then try me:

<a href="mailto:ejcampos@ucla.edu">&nbsp; ejcampos@ucla.edu</a> 
<a href="http://twitter.com/emjcampos">&nbsp; @emjcampos</a> 
<a href="http://github.com/emjcampos">&nbsp; @emjcampos</a>

Slides available at [http://bit.ly/bsa-blogdown-2020](http://bit.ly/bsa-blogdown-2020).