+ - 0:00:00
Notes for current slide
Notes for next slide

Up and Running with blogdown

A workshop for the Portland R User Group

Alison Presmanes Hill

2017-09-14

1 / 72

Keep in touch

  apresstats@gmail.com
  apreshill.rbind.io
  @apreshill
  @apreshill
  OHSU Center for Spoken Language Understanding

2 / 72

3 / 72

blogdown

4 / 72

blogdown

An R package for creating websites using R Markdown and Hugo

4 / 72

blogdown

An R package for creating websites using R Markdown and Hugo

4 / 72

You don't have to blog to use blogdown

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

5 / 72

How to do this workshop

Just watch

http://hyperboleandahalf.blogspot.com

6 / 72

How to do this workshop

Do it with me

http://hyperboleandahalf.blogspot.com

7 / 72

Do the workshop with me

Download the workshop bundle materials from my github repo: https://github.com/apreshill/blogdown-workshop

8 / 72

Get Started

9 / 72

Install blogdown

blogdown was released on CRAN this week!

install.packages("blogdown")
10 / 72

Install blogdown

blogdown was released on CRAN this week!

install.packages("blogdown")

Or use the development version:

if (!requireNamespace("devtools")) install.packages("devtools")
devtools::install_github("rstudio/blogdown")
10 / 72

Install Hugo using blogdown

blogdown::install_hugo()
# or
library(blogdown)
install_hugo()
11 / 72

Install Hugo using blogdown

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

Other relevant functions:

blogdown::update_hugo() # force an update
blogdown::hugo_version() # check version
11 / 72

Make a site

12 / 72

Create a new R Project

You are recommended to use the RStudio IDE, but you do not have to.

  • Create a new R Project from the menu File -> New Project -> New Directory
13 / 72

Update R Project Options

https://bookdown.org/yihui/blogdown/rstudio-ide.html#fig:project-options

14 / 72

Updated RStudio Project Templates

https://blog.rstudio.com/2017/09/13/rstudio-v1.1---the-little-things/

Note: you'll be able to install Hugo automatically if you use this method.

15 / 72

Build your site

  • Default theme (we will work with this tonight)
blogdown::new_site()
16 / 72

Build your site

  • Default theme (we will work with this tonight)
blogdown::new_site()
  • Different theme
blogdown::new_site(theme = "gcushen/hugo-academic", 
                   theme_example = TRUE)
16 / 72

Build your site

  • Default theme (we will work with this tonight)
blogdown::new_site()
  • Different theme
blogdown::new_site(theme = "gcushen/hugo-academic", 
                   theme_example = TRUE)
  • Change your mind
blogdown::install_theme("gcushen/hugo-academic", 
                        theme_example = TRUE, 
                        update_config = TRUE)
16 / 72

Explore your site

17 / 72

Hello Hugo

18 / 72

Hugo Directory Structure

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

Know your way around:

.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── public
├── static
└── themes
19 / 72

Directory names

  • Trailing slash will indicate a directory name, e.g., content/ means a directory named content instead of a file named content.
.
├── archetypes
├── config.toml
├── content
|   └── posts
├── data
├── layouts
├── public
├── static
└── themes
20 / 72

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.
.
├── archetypes
├── config.toml
├── content 
├── data
├── layouts
├── public
├── static
|   └──  css
|        └──  style.css
└── themes
21 / 72

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.

22 / 72

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.

Note which folders are empty at the top level of your project:

.
├── archetypes
├── config.toml
├── content
├── data
├── layouts
├── public
├── static
└── themes
22 / 72

Serve site

  • Console
blogdown::serve_site()
23 / 72

Serve site

  • Console
blogdown::serve_site()
  • or RStudio Addin (recommended)
23 / 72

LiveReLoad

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

  1. Edit + save triggers
24 / 72

LiveReLoad

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

  1. Edit + save triggers

  2. Blocks your console by design

24 / 72

LiveReLoad

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

  1. Edit + save triggers

  2. Blocks your console by design

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

24 / 72

Edit your site

25 / 72

Edit your site

26 / 72

Edit your site

Starting now, the numbers of each file will correspond to which edit we are working on.

27 / 72

Edit 1: add 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/

28 / 72

Edit 1: add 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/
28 / 72

Edit 1: add 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/

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

28 / 72

Edit 1: add 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/

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

  3. Update config.toml and save

  [params.logo]
     url = "rladies-r-logo.png" 
    width = 50
    height = 50
    alt = "Logo"
28 / 72

Edit 1: did we add a logo?

29 / 72

Edit 1: did we learn something?

Yes!

30 / 72

Edit 1: did we learn something?

Yes!

We saw:

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

30 / 72

Edit 1: did we learn something?

Yes!

We saw:

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

Could be overwritten by:

/static/images/<rladies-r-logo.png>

30 / 72

Edit 1: did we learn something?

Yes!

We saw:

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

Could be overwritten by:

/static/images/<rladies-r-logo.png>

The filename <rladies-r-logo.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/

30 / 72

Edit your site

 Edit 2: update the "About" page

31 / 72

Edit 2: update the "About" page

  1. Move 02-about.md file to /content/
32 / 72

Edit 2: update the "About" page

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

  2. Delete the existing file about.md

32 / 72

Edit 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 1

[1] you should still have LiveReLoad running...

32 / 72

Edit 2: did we change the about page?

33 / 72

Edit 2: did we learn something?

Yes!

/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/

34 / 72

Edit 2: did we learn something?

Yes!

/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/

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

Edit your site

 Edit 3: emojis 🙈🙉🙊

35 / 72

Edit 3: enable emojis

  • Top of your config.toml file
36 / 72

Edit 3: enable emojis

  • Top of your config.toml file

  • Note the last line 😉

baseurl = "/"
languageCode = "en-us"
title = "R-Ladies PDX" 
theme = "hugo-lithium-theme"
googleAnalytics = ""
disqusShortname = ""
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]
enableEmoji = true
36 / 72

Edit 3: enable emojis

  • Top of your config.toml file

  • Note the last line 😉

baseurl = "/"
languageCode = "en-us"
title = "R-Ladies PDX" 
theme = "hugo-lithium-theme"
googleAnalytics = ""
disqusShortname = ""
ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]
enableEmoji = true
  • In your "About" page, :heart: should now be ❤️
36 / 72

Edit 3: did we learn something?

Yes!

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

37 / 72

Edit 3: did we learn something?

Yes!

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)

37 / 72

Edit your site

 Edit 4: change the navigation bar

38 / 72

Edit 4: change the navigation bar

In your config.toml file:

[[menu.main]]
    name = "About"
    url = "/about/"
   weight = 1
[[menu.main]]
   name = "Meetups"
   url = "https://www.meetup.com/R-Ladies-PDX/"
   weight = 2
[[menu.main]]
    name = "Twitter"
   url = "https://twitter.com/RLadiesPDX"
   weight = 3
39 / 72

Edit 4: did we change the navigation bar + links?

40 / 72

Edit 4: did we learn something?

Yes!

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/

41 / 72

Edit your site

 Edit 5: colors, fonts, styles

42 / 72

Edit 5: customize CSS

  1. In /static/ create a new directory css
43 / 72

Edit 5: customize CSS

  1. In /static/ create a new directory css

  2. Move 05-rladies.css file to /static/css/

43 / 72

Edit 5: customize CSS

  1. In /static/ create a new directory css

  2. Move 05-rladies.css file to /static/css/

  3. Rename 05-rladies.css --> rladies.css

43 / 72

Edit 5: customize CSS

  1. In /static/ create a new directory css

  2. Move 05-rladies.css file to /static/css/

  3. Rename 05-rladies.css --> rladies.css

  4. In config.toml, add last line: 1

[params]
   description = "A website built through Hugo and blogdown."
   customCSS = ["css/rladies.css"]

[1] how did I know the name of this parameter? 🕵🏽 /themes//layouts/partials/head.html

43 / 72

Edit 5: did we change the CSS?

44 / 72

Edit 5: did we learn something?

Yes!

45 / 72

Edit 5: did we learn something?

Yes!

We saw:

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

45 / 72

Edit 5: did we learn something?

Yes!

We saw:

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

Could be overwritten by style rules present in:

/static/<css/rladies.css>

45 / 72

Edit 5: did we learn something?

Yes!

We saw:

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

Could be overwritten by style rules present in:

/static/<css/rladies.css>

The directory/filename <css/rladies.css> could have been anything, because there is a place to specify the url in the config.toml file

45 / 72

Edit your site

 Edit 6: add awesome icons

     

46 / 72

Edit 6: add awesome icons

About Font Awesome:

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.

47 / 72

Edit 6: add awesome icons

About Font Awesome:

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 to enter your email address and receive a Font Awesome embed code. We'll use mine for demo tonight.

47 / 72

Edit 6: add awesome icons

About Font Awesome:

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 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
  2. a script that directs your site to where the fonts can be found (via Font Awesome's Content Delivery Network, or CDN)
47 / 72

Edit 6: add 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/
48 / 72

Edit 6: add 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/

  2. Create a new directory in layouts/ called partials

48 / 72

Edit 6: add 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/

  2. Create a new directory in layouts/ called partials

  3. Move other head_custom.html and nav.html to /layouts/partials/

    • Why? Let's open them up and take a look
48 / 72

Edit 6: add 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/

  2. Create a new directory in layouts/ called partials

  3. 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, for example, you could add them to your About page:

For more information, contact us at <i class="fa fa-envelope-open" aria-hidden="true"></i><mailto:pdx@rladies.org>.

For more information, contact us at  pdx@rladies.org.

48 / 72

Edit 6: final steps to add icons

Make changes to these sections in your config.toml:

[[menu.main]]
    name = "About"
    pre = "" 
    url = "/about/"
    weight = 1
[[menu.main]]
    name = "Meetups"
    pre = "fa-meetup" 
    url = "https://www.meetup.com/R-Ladies-PDX/"
    weight = 2
[[menu.main]]
    name = "Twitter"
    pre = "fa-twitter"
    url = "https://twitter.com/RLadiesPDX"
    weight = 3
[params]
    description = "A website built through Hugo and blogdown."
    customCSS = ["css/rladies.css", "css/font-awesome.min.css"]
49 / 72

Edit 6: are there awesome icons?

50 / 72

Edit 6: did we learn something?

...

51 / 72

Edit 6: did we learn something?

...

Yes!

We saw:

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

51 / 72

Edit 6: did we learn something?

...

Yes!

We saw:

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

Could be overwritten by:

/layouts/partials/*<PARTIALNAME>.html

51 / 72

Edit 6: did we learn something?

...

Yes!

We saw:

/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/

51 / 72

Edit your site

 Edit 7: make a homepage

52 / 72

Edit #7: 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
53 / 72

Edit #7: 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

Which file on our site is currently serving as the homepage template?

53 / 72

Edit 7: make a homepage

  • Where should we move the file index.html?
54 / 72

Edit 7: make a homepage

  • Where should we move the file index.html?

  • Move index.html --> /layouts/ 1

[1] NOT to /layouts/partials/

54 / 72

Edit 7: edit the homepage

Edit the config.toml file

[params]
   description = "R-Ladies PDX is part of a world-wide organization 
     to promote gender diversity in the R community. <br>
     To find more details about the R-Ladies global initiative, 
     visit [rladies.org](https://rladies.org)."
   chapter = "Portland, Oregon"
   customCSS = ["css/rladies.css", "css/font-awesome.min.css"]
55 / 72

Edit 7: edit the homepage

Edit the config.toml file

[params]
   description = "R-Ladies PDX is part of a world-wide organization 
     to promote gender diversity in the R community. <br>
     To find more details about the R-Ladies global initiative, 
     visit [rladies.org](https://rladies.org)."
   chapter = "Portland, Oregon"
   customCSS = ["css/rladies.css", "css/font-awesome.min.css"]

Note that the chapter parameter is new. Now, this is a variable that can be referenced in templates as:

{{ .Site.Params.Chapter }}

55 / 72

Edit 7: do we have a new homepage?

56 / 72

Edit 7: did we learn something?

Yes!

We saw that, even when there is no file here:

/themes/<THEME>/layouts/index.html

57 / 72

Edit 7: did we learn something?

Yes!

We saw that, even when there is no file here:

/themes/<THEME>/layouts/index.html

We can make one here that serves as the homepage:

/layouts/index.html

57 / 72

Edit 7: did we learn something?

Yes!

We saw that, even when there is no file here:

/themes/<THEME>/layouts/index.html

We can make one here that serves as the homepage:

/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/

57 / 72

Edit your site

 Edit 8: hey wait! where are my posts?

58 / 72

Edit 8: hey wait! where are my posts?

How can we get them back? Ideas?

59 / 72

Edit 8: hey wait! where are my posts?

How can we get them back? Ideas?

Try adding this in the config.toml file: 

[[menu.main]]
    name = "Twitter"
    pre = "fa-twitter"
    url = "https://twitter.com/RLadiesPDX"
    weight = 3
[[menu.main]]
    name = "News"
    pre = "fa-bullhorn"
    url = "/post/"
    weight = 4
59 / 72

Edit 8: do we have news?

60 / 72

Edit 8: did we learn something?

Yes!

61 / 72

Edit 8: did we learn something?

Yes!

While Hugo supports content nested at any level, the top levels (i.e. /content/<DIRECTORIES>) are special in Hugo

https://gohugo.io/content-management/organization/

61 / 72

Edit 8: did we learn something?

Yes!

While Hugo supports content nested at any level, the top levels (i.e. /content/<DIRECTORIES>) are special in Hugo

https://gohugo.io/content-management/organization/

Without any additional configuration, the following will just work:

.
└── content
    └── post
        ├── firstpost.md   <<- https://example.com/post/firstpost/
        └── happy
            └── ness.md  <<- https://example.com/post/happy/ness/
61 / 72

Deploy your site

62 / 72

Deployment

  • The publishing directory is by default /public/.
63 / 72

Deployment

  • The publishing directory is by default /public/.

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

63 / 72

Deployment

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

63 / 72

Deployment

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

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

63 / 72

Deployment

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

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
63 / 72

I recommend Netlify

64 / 72

How to git from the start

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

65 / 72

How to git at the end

http://happygitwithr.com/existing-github-last.html

66 / 72

Netlify deploy settings

67 / 72

Netlify site name

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

On Netlify, go into General -> Site details -> Site information -> Change site name and update

68 / 72

rbind subdomains

69 / 72

Final edit: update baseurl

Top of your config.toml

baseurl = "https://rladies-pdx.rbind.io/"

On Netlify, go into Domain settings -> Custom domain and update

70 / 72

More resources

A minimal website example using blogdown Site: https://blogdown-demo.netlify.com GitHub: https://github.com/apreshill/blogdown-demo

Includes using citations in posts, including Rmd files of other output formats, and embedding htmlwidgets in posts

View the actual demo site: https://rladies-pdx.netlify.com

More on posting here: https://apreshill.rbind.io/post/up-and-running-with-blogdown/#build-your-site-in-rstudio

And here: https://bookdown.org/yihui/blogdown/output-format.html

71 / 72

Thanks!

To Yihui and RStudio for the blogdown package

To Yihui and Amber for inviting me to be a co-author on the blogdown book

To the rbind group for awesome support

To the R-Ladies PDX organizers, Augustina and Deeksha, for allowing me to use them as a guinea pig- join the R-Ladies PDX meetup group!

Slides created via the R package xaringan.

72 / 72

Keep in touch

  apresstats@gmail.com
  apreshill.rbind.io
  @apreshill
  @apreshill
  OHSU Center for Spoken Language Understanding

2 / 72
Paused

Help

Keyboard shortcuts

↑, ←, Pg Up, k Go to previous slide
↓, →, Pg Dn, Space, j Go to next slide
Home Go to first slide
End Go to last slide
Number + Return Go to specific slide
b / m / f Toggle blackout / mirrored / fullscreen mode
c Clone slideshow
p Toggle presenter mode
t Restart the presentation timer
?, h Toggle this help
Esc Back to slideshow