Build your website using R, RStudio and blogdown package

# Build your website using R, RStudio and blogdown package
## DataTeka
### Tatjana Kecojevic

---

background-image: url(https://upload.wikimedia.org/wikipedia/commons/c/c1/Rlogo.png)
???

Image credit: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Rlogo.png)
---

Hi, Welcome to the **'Build your website using R, RStudio and blogdown package'** workshop.

I'm Tanja! A Data Scientist at [DataTeka](https://datateka.com/). A year ago I quit my job in academia and moved to Belgrade to play a part in establishing data science in the Balkan region. Recently, I started an initiatve `klikR` for introducing Data Science through R to youngsters as their possible career option. [klikR's](http://klikr.rbind.io) website is created using `blogdown` 😃.

The goal of our workshop is to work through the material and to lern how to use [blogdown](https://cran.r-project.org/web/packages/blogdown/index.html) package to make a web site.

---
class: inverse, middle
Go to <https://github.com/TanjaKec/WiDS> to download the material.

<img src="images/GitHub_link2.png" width="550px" style="display: block; margin: auto;" />
---
class: inverse, center, middle

#Get Started 🤫😴
<img src="images/George_Desk.gif" width="600px" />

---
class: center, middle

---
## 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)

---
## 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
.footnote[
[\*] From Yihui: https://slides.yihui.name/2017-rmarkdown-UNL-Yihui-Xie.html#36.
]

---
class: inverse, center, middle

# Let us start practicing Elain's Dance!!! 😃🎵🎶
<img src="images/ElainDanceI.png" width="300px" style="display: block; margin: auto;" />

---
## Prep with GitHub

The workshop will not go through [Happy Git with R](http://happygitwithr.com) to connect RStudio with your GitHub account.

We are going to assume that you are already familiar and have done:

☑️ Capter 5: [Register a GitHub account ](http://happygitwithr.com/github-acct.html)

☑️ Chapter 6: [Install or upgrade R and RStudio ](http://happygitwithr.com/install-r-rstudio.html)

---
Go to your GitHub account and create a new repository
<img src="images/New_Repo.png" width="200px" style="display: block; margin: auto 0 auto auto;" />

Give a meaningful name 
<img src="images/Create_New_Repo.png" width="300px" style="display: block; margin: auto;" />

Copy repo's **HTTPS** address
<img src="images/HTTPS_GitHub.png" width="350px" style="display: block; margin: auto;" />

---
Open a new project in RStudio: **File** ➡️ **New Project...**
<img src="images/RS_New_Project.png" width="250px" style="display: block; margin: auto;" />
Select **Version Control** ➡️ **Git**
<img src="images/Select_Version_Control.png" width="250px" style="display: block; margin: auto;" />

Paste the address of your Git repo 
<img src="images/set_up_git_connection.png" width="250px" style="display: block; margin: auto;" />

---
## Install the packages

Install `blogdown`*

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

Install `Hugo` using blogdown

```r
blogdown::install_hugo()
```

If you already got those packages installed you can chech to update your `Hugo` package

```r
blogdown::hugo_version() # check version
blogdown::update_hugo() # force an update
```
 
.footnote[
[\*] If you having trouble installing the package try:

`install.packages("blogdown", repos = "http://cran.us.r-project.org")`.🤞
]

---
class: inverse, center, middle
# Let's build a website...

---
##Build a website

We'll adopt *simple is beautiful* approch and start building a website using a `default theme`*.

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

To use a different theme (for example: `hugo-academic`):

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

To see the current **Hugo themes** go to <https://themes.gohugo.io/>.

.footnote[
[\*]Let the knowledge and familiarity with `blogdown` and `Hugo` grow first.🧐 Once you get familiour with `blogdown` and `Hugo` you can always swich to a different theme. 💇
https://bookdown.org/yihui/blogdown/other-themes.html
]

---
###Structure of a HUGO site
.pull-left[
<img src="images/Site_Structure.png" width="200px" style="display: block; margin: auto;" />
]
.pull-right[
<img src="images/main_structure.png" width="200px" style="display: block; margin: auto;" />
]

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

Note which folders are empty at the top level of your project:
<img src="images/empty_dir_str.png" width="200px" style="display: block; margin: auto;" />
<https://gohugo.io/themes/theme-components/>

---
### Serve site

In console type:

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

or, from `Addins` menue select `servesite`

Don't try to view your site in your teeny RStudio viewer, instead click on `Show in new window`.

---
### Notation we will adopt

- **Trailing slash** will indicate a directory name, e.g. `content/` means we are refering to a directory called *content*, not to a file named *content*.

- **Leading slash** indicate the root directory of your *project website*, e.g. `/content/about.md` means we are refering to `about.md` file which is under the root directory of the website project.

---
class: inverse, center, middle
# Let's edit our website...

---
class: inverse, center, middle
#Step 1: logo 🛠⚙️💡

---
###Step 1: add a logo
<img src="images/DataTekaHex.png" width="80px" style="display: block; margin: auto auto auto 0;" />
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/`

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

3. Update `config.toml` and save
<img src="images/update_config.png" width="250px" style="display: block; margin: auto auto auto 0;" />
---
###Step 1: we've got a logo!

<img src="images/logo_page01.png" width="800px" style="display: block; margin: auto;" />
---
###Step 1: we've learnt 🥁🎺😎

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

can be overwritten by

`/static/images/<DataTeka_logo.png>`

.pull-left[
<img src="images/overwrite_logo1.png" width="250px" style="display: block; margin: auto;" />
]

.pull-right[
<img src="images/overwrite_logo2.png" width="250px" style="display: block; margin: auto;" />
]

.footnote[
Note that this would work only with Hugo templates that have 'standard' Hugo folder structure.💡
]
---

class: inverse, center, middle
#Step 2: about 🛠⚙️💡
---
###Step 2: update the *about* page

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

2. Delete the existing file `about.md`

3. Rename `02-about.md` → `about.md`
---

###Step 2: we've got a logo!

<img src="images/about_page02.png" width="800px" style="display: block; margin: auto;" />
---

###Step 2: we've learnt 🥁🎺😎

>All `content` for your website will live inside this directory. Each top-level folder in Hugo is considered a content section. For example, if your website has two main sections *posts* and *about* page, there will be a directorie at `content/posts` and a file `content/about.md`.

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

<img src="images/about_structure.png" width="200px" style="display: block; margin: auto;" />
---
class: inverse, center, middle
#Step 3: emojis 🛠⚙️💡
---
###Step 3: enable the emojis 😁🤷🤦

Note the amendments you need to do to the top of your `config.toml` file.

Save the change and check the *about* page... it should show a ❤️

---
###Step 3: we've learnt 🥁🎺😎

> In your `config` file, you can direct Hugo as to how you want your website rendered, control your website’s menus, and arbitrarily define site-wide parameters specific to your project.

<https://gohugo.io/getting-started/configuration/>

---
class: inverse, center, middle
#Step 4: navigation bar 🛠⚙️💡
---
###Step 4: edit your navigation bar

Make the changes to your `config.toml` file:

Save the changes, Serve Site and check the links.

---
###Step 4: we've learnt 🥁🎺😎

The `[[menu.main]]` in your `config` file enables you to edit and add navigation options.

> A menu entry in a menu-template has specific variables and functions to make menu management easier.

<https://gohugo.io/variables/menus/>
---
class: inverse, center, middle

##Are we starting to feel confortable learning Elain's moves?! 😃🎵🎶

<img src="images/ElainDanceII.png" width="300px" />
---
class: inverse, center, middle
#Step 5: css 🛠⚙️💡
---
###Step 5: customise the look 💅💄🎨

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

2) Move `05-datateka.css` file to `/static/css/`

3) Rename `05-datateka.css` --> `datateka.css`

<img src="images/css_structure.png" width="200px" style="display: block; margin: auto auto auto 0;" />
--

4) In `config.toml`, add the highlighted line:

---
###Step 5: we've got a look! 
<img src="images/css_page05.png" width="700px" style="display: block; margin: auto;" />

---
###Step 5: we've learnt 🥁🎺😎

We have seen that

`/themes/<THEME>/static/css/main.css`

could be overwritten by style rules present in:

`/static/<css/datateka.css>`

<img src="images/overwrite_css_structure.png" width="300px" style="display: block; margin: auto;" />
---
class: inverse, center, middle
#Step 6: Font Awesome 🛠⚙️💡
---
###Step 6: use Font Awesome

> Font Awesome is a font and icon toolkit based on CSS and LESS.

<https://en.wikipedia.org/wiki/Font_Awesome>

Go [here](https://fontawesome.com/v4.7.0/get-started/) to enter your email address and receive a Font Awesome embed code. We'll use the one you've downloaded with the workshop boundle for today's demo.

To use them, you need 2 things:

- the Font Awesome CSS file, and

- a script that directs your site to where the fonts can be found (via Font Awesome's Content Delivery Network, or CDN)

---
###Step 6: use Font Awesome

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

2a) Rename `06a-font-awesome.min.css` --> `font-awesome.min.css`

3b) Create a new directory `layouts/` and within create a subdirectory called `partials`

4b) Move other `06b-head_custom.html` and `06b-nav.html` to `/layouts/partials/` and renamed them by removing `06b-` from the files names.

<img src="images/fontawsome_structure.png" width="300px" style="display: block; margin: auto;" />
---
###Step 6: use Font Awesome

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

---
###Step 6: look at our awesome font and icons!

---
###Step 6: we've learnt 🥁🎺😎

`/themes/<THEME>/layouts/partials/*<PARTIALNAME>.html`

Could be overwritten by:

`/layouts/partials/*<PARTIALNAME>.html`

The `<PARTIALNAME>`s must match; unless you want to edit how the partials are called within your templates:

`{{ partial "<PATH>/<PARTIAL>.html" . }}`
 
https://gohugo.io/templates/partials/

<img src="images/learn_structure_fontawsome.png" width="250px" style="display: block; margin: auto auto auto 0;" />
---
class: inverse, center, middle
#Step 7: homepage 🛠⚙️💡
---
###Step 7: create a homepage

Where to move the file `07-index.html`?

1) Move `07-index.html` to `/layouts/`*

2) Rename `07-index.html` to `index.html`

3) Edit the `config.toml` file

---
###Step 7: look at our home page!

---
###Step 7: we've learnt 🥁🎺😎

Even when there is no `index.html` file here:
 
`/themes/<THEME>/layouts/index.html`

We can make one that serves as the homepage here:

`/layouts/index.html`

The filename `index.html` has special status in Hugo, and is **not** a partial layout template.

You could also force a homepage by creating an `_index.md` file that lives at the root of your `/content/` folder (i.e., `/content/_index.md`)

<https://gohugo.io/templates/homepage/>
---
class: inverse, center, middle
#Step 8: posts 🛠⚙️💡
---
###Step 8: adding a post

Add a post section to your navigation bar by adding the highlighted lines to your `config.toml` file.

<img src="images/post_config.png" width="400px" style="display: block; margin: auto auto auto 0;" />
---
###Step 8: we've got a link for the posts!

<img src="images/overview_post08.png" width="600px" style="display: block; margin: auto;" />
---
###Step 8: write a post ✍️
Go to `Addins` and select `New Post` to which you are going to add the properties
.pull-left[
<img src="images/add_a_post.png" width="200px" style="display: block; margin: auto;" />
]
.pull-right[
<img src="images/create_a_post.png" width="275px" style="display: block; margin: auto;" />
]

You can start writting your post as an R Markdown file 😊
<img src="images/edit_write_post.png" width="250px" style="display: block; margin: auto;" />

---
###Step 8: we've got our first posts!

---
###Step 8: removing the `default` posts 🤷

Click on the `Files` tab and navigate to `/content/post/` directory to get the list of the *posts files*

Select the once you don't want and click on `Delete` ❌.

`Serve Site` to have a look

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

---
###Step 8: look at your posts!

<img src="images/overview_posts02.png" width="700px" style="display: block; margin: auto;" />
---
###Step 8: we've learnt 🥁🎺😎

Adding a post is easy by selection the option `New Post` from the `Addins` drop-down menu and writing it as a `.Rmd` file. This file will be authomaticaly placed inside `/content/posts/` directory.

`/content/posts/workshop-at-nwurday-with-tanja.Rmd`

<img src="images/posts_structure.png" width="400px" style="display: block; margin: auto auto auto 0;" />
---
class: inverse, center, middle

##Let's do Elain's Dance!!! 😃🎵🎶

<img src="images/Elain_dance.gif" width="500px" />
---

# Deploy your website 🧞

---
### Deployment

Click on the `Git` tab and select all of the files to `commit`

<img src="images/first_commit.png" width="600px" style="display: block; margin: auto auto auto 0;" />
---

Click to `push`

<img src="images/git_push01.png" width="500px" style="display: block; margin: auto auto auto 0;" />
---
### Check your Git Repo

<img src="images/gitrepo.png" width="750px" style="display: block; margin: auto;" />
---
class: inverse, center, middle

###Congratulations! You are a step away from making your website up and running!!!! 👍😃

<img src="images/kramer_congrats.gif" width="300px" />
---
### Have you heard about [Netlify](https://www.netlify.com/)?

> Consider Netlify instead of GitHub Pages for Your Static Websites.

> Do not use Github pages or the *.github.io subdomain. Use Netlify instead. Netlify is the new and much better Github pages.

*Yihui Xie*

<https://yihui.name/en/2017/06/netlify-instead-of-github-pages/>
---

> Deploying in Netlify through GitHub is smooth.

> When you are ready to deploy, commit your changes and push to [GitHub](https://github.com), then go online to [Netlify](https://www.netlify.com/).

*Alison Presmanes Hill*

<https://alison.rbind.io/post/up-and-running-with-blogdown/>
---
Go to [Netlify](https://www.netlify.com/) and open an account (the esiest is by using your [GitHub](https://github.com) login).

Click on *New site from Git* button

Select *GitHub* option to *Continue Deployment*.

---
Selct your site repo and klick on *Deploy site* button at the bottom of the page.

<img src="images/deploy_site.png" width="700px" style="display: block; margin: auto;" />
---
Go into *Site Setting* and click on *Change site name*.

<img src="images/change_site_name.png" width="700px" style="display: block; margin: auto;" />
---
class: center, middle

<img src="images/site_on_netlify.png" width="900px" style="display: block; margin: auto;" />
---
### You can hoste your site as `rbind` subdomain 
<img src="images/rbind.png" width="10%" align="left" />
[rbind](https://github.com/rbind) - Bind all websites in the `R` and `stats` community.

<http://klikr.rbind.io> is an example of what to request if you wish to move your site to [rbind](https://github.com/rbind). 
<img src="images/rbind_support.png" width="500px" style="display: block; margin: auto;" />
---
### Final step: update `baseurl` in your `config.toml`
<img src="images/baseurl.png" width="500px" style="display: block; margin: auto;" />

On [Netlify](https://www.netlify.com/), go into *Domain settings -> Custom domain* and update

<https://support.rbind.io/about/>
---

### Some useful links

[RStudio: Making websites with Markdown](https://www.rstudio.com/resources/webinars/introducing-blogdown/)

A tutorial on using `blogdown`.

<https://blogdown-demo.netlify.com> GitHub: <https://github.com/apreshill/blogdown-demo>

A minimal website example using blogdown site by [Alison Presmanes Hill](https://alison.rbind.io).

--
[Up and running with blogdown](https://alison.rbind.io/post/up-and-running-with-blogdown/#build-your-site-in-rstudio)

[Alison's](https://amber.rbind.io/) well structurd and easy to follow tutorial higlighting the key steps when building a weisite using blogdown.

[`blogdown`: Creating Websites with R Markdown](https://bookdown.org/yihui/blogdown/)

by [Yihui Xie](https://yihui.name/), [Amber Thomas](https://amber.rbind.io/), [Alison Presmanes Hill](https://alison.rbind.io)
---

class: inverse, center, middle
##Do the Cosmo Dance?! 🤪🎵🎶
<img src="images/Cosmo_Dance.gif" width="500px" />

---
class: center, middle

##Thanks!

To Yihui and RStudio for the blogdown package

To the rbind group for support

Special thanks to Alison for sharing her knowledge and making her material reproducable and freely available. This workshop has been created with Alison's support and it is based on her 'up and running with blogdown tutorial' available at <https://github.com/apreshill/blogdown-workshop>

Please provide a feedback by filling the form:

<https://datateka.shinyapps.io/NURDay_Form>

[www.datateka.com](www.datateka.com)

[tanjakec.github.io](tanjakec.github.io)

@DataTeka

@Tatjana_Kec

Slides created via `R` package [**xaringan**](https://github.com/yihui/xaringan).

The chakra comes from [remark.js](https://remarkjs.com), [**knitr**](http://yihui.name/knitr), and [R Markdown](https://rmarkdown.rstudio.com).