class: center, middle, inverse, title-slide # Lab 06: BMI 5/625 ## Making a Site in the Tada!-verse <br> Part One: Build a Site ### Alison Hill (with mods by Steven Bedrick) --- class: center, middle, inverse ## Sites with `blogdown` --- background-image: url("https://media.giphy.com/media/3o6ozfM60Gc64dN0A0/giphy.gif") background-size: cover --- class: middle, center  --- ## So what is blogdown?<sup>*</sup> - [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) .footnote[ [\*] From Yihui: https://slides.yihui.name/2017-rmarkdown-UNL-Yihui-Xie.html#35. ] ??? 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?<sup>*</sup> - 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. ] ??? 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:middle, center, inverse  --- # In RStudio File ➡️ New Project ➡️ New Directory ➡️ Website using blogdown <img src="../images/website-using-blogdown.png" width="80%" style="display: block; margin: auto;" /> --- # Next in RStudio <img src="../images/install-cocoa-eh-theme.png" width="80%" style="display: block; margin: auto;" /> Note: Use `stevenbedrick/cocoa-eh-hugo-theme` --- # Open your new project <img src="../images/hugo-initial-files.png" width="80%" style="display: block; margin: auto;" /> --- class: inverse, middle, center # ⚠️ ## If you have already used `blogdown`, you'll want to update your Hugo: ```r # force an update blogdown::update_hugo() # check your version blogdown::hugo_version() ``` --- # Mini-orientation to Hugo https://gohugo.io/getting-started/directory-structure/ ```r . ├── .Rhistory ├── archetypes ├── config.toml ├── content ├── data ├── index.Rmd ├── your .Rproj file ├── layouts ├── static └── 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.* -- Note which folders are *empty* at the top level of your project: ```r . ├── .Rhistory *├── archetypes ├── config.toml ├── content *├── data ├── index.Rmd ├── your .Rproj file *├── layouts ├── static └── themes ``` --- # Open themes Look in `/themes/cocoa-eh-hugo-theme/`. Notice now the folder structure here *mirrors* your Hugo directory structure. <img src="../images/hugo-theme-directory.png" width="80%" style="display: block; margin: auto;" /> --- # Override files in... .pull-left[ your theme directory... ```r . *├── archetypes ├── exampleSite ├── images *├── layouts *└── static ``` ] .pull-right[ with files in your project directory. ```r . ├── .Rhistory *├── archetypes ├── config.toml ├── content ├── data ├── index.Rmd ├── your .Rproj file *├── layouts *├── static └── themes ``` ] --- class: middle, inverse, center # 🏡 ## Edit/Review the configuration file --- # Open `config.toml` - TOML<sup>*</sup> is like YAML, but not 😂 .pull-left[ ```r +++ title = "Lab 06: BMI 5/625" tags = ["toml","yaml"] type = "article" [amp] elements = [] [article] lead = "Lorem ipsum." category = "frontmatter" related = [] +++ ``` ] .pull-right[ ```r --- title: "Lab 06: BMI 5/625" tags: - toml - yaml type: article amp: elements: [] article: lead: Lorem ipsum. category: frontmatter related: [] --- ``` ] .footnote[ [\*] https://gohugohq.com/howto/toml-json-yaml-comparison/ ] --- # Open `config.toml` - blocks wrapped by `+++` vs `---` <sup>*</sup> - Your `config.toml` file doesn't show this explicitly but it is there! .pull-left[ ```r *+++ title = "Lab 06: BMI 5/625" tags = ["toml","yaml"] type = "article" [amp] elements = [] [article] lead = "Lorem ipsum." category = "frontmatter" related = [] *+++ ``` ] .pull-right[ ```r *--- title: "Lab 06: BMI 5/625" tags: - toml - yaml type: article amp: elements: [] article: lead: Lorem ipsum. category: frontmatter related: [] *--- ``` ] .footnote[ [\*] https://gohugohq.com/howto/toml-json-yaml-comparison/ ] --- # Open `config.toml` - key-value pairs are separated by a `=` vs `:` <sup>*</sup> .pull-left[ ```r +++ *title = "Lab 06: BMI 5/625" tags = ["toml","yaml"] type = "article" [amp] elements = [] [article] lead = "Lorem ipsum." category = "frontmatter" related = [] +++ ``` ] .pull-right[ ```r --- *title: "Lab 06: BMI 5/625" tags: - toml - yaml type: article amp: elements: [] article: lead: Lorem ipsum. category: frontmatter related: [] --- ``` ] .footnote[ [\*] https://gohugohq.com/howto/toml-json-yaml-comparison/ ] --- # Open `config.toml` - YAML uses indentation with one or more spaces to describe nested collections <sup>*</sup> .pull-left[ ```r +++ title = "Lab 06: BMI 5/625" *tags = ["toml","yaml"] type = "article" [amp] elements = [] [article] lead = "Lorem ipsum." category = "frontmatter" related = [] +++ ``` ] .pull-right[ ```r --- title: "Lab 06: BMI 5/625" *tags: *- toml *- yaml type: article amp: elements: [] article: lead: Lorem ipsum. category: frontmatter related: [] --- ``` ] .footnote[ [\*] https://gohugohq.com/howto/toml-json-yaml-comparison/ ] --- # Edit `config.{toml|yaml}` - Set `baseurl` - Change the `author` and `title` properties - Tell Hugo to ignore `Rmd` files - (`blogdown` will be taking care of those for us) ```r *baseurl = "/" theme = "cocoa-eh-hugo-theme" builddrafts = true canonifyurls = true contentdir = "content" languageCode = "en-US" layoutdir = "layouts" publishdir = "public" *author = "Ada Lovelace" *title = "Ada Lovelace" disqusshortname = "" pluralizelisttitles = false *ignoreFiles: ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"] ``` - Review the other entries --- class: center, inverse, middle # Serve site! Mouse up to "Addins" ➡️ "Serve site"  --- # Success? <img src="../images/cocoa-in-viewer.png" width="80%" style="display: block; margin: auto;" /> --- ## Go back to your project root directory *New*: the `public` folder <img src="../images/serve-site-public.png" width="75%" style="display: block; margin: auto;" /> --- # Go back to `config.toml` ```r baseurl = "/" theme = "cocoa-eh-hugo-theme" builddrafts = true canonifyurls = true contentdir = "content" languageCode = "en-US" layoutdir = "layouts" publishdir = "public" author = "Ada Lovelace" title = "Ada Lovelace" disqusshortname = "" pluralizelisttitles = false ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"] *enableEmoji = true ``` --- # Update logo Mouse over the `static/img/` and see `logo.png`? We can replace that file, or make new file. I'll replace mine with [this picture](https://en.wikipedia.org/wiki/Ada_Lovelace). ```r [permalinks] blog = "blog/:slug/" [params] dateform = "Jan 2, 2006" dateformfull = "Mon Jan 2 2006 15:04:05 MST" *description = "Professional website" *copyright = "Copyright © 2015 Ada Lovelace" *copyrightUrl = "https://creativecommons.org/licenses/by-sa/4.0/" *logofile = "img/ada.jpg" faviconfile = "img/logo.png" highlightjs = true progressively = true share = true ``` --- # Success? <img src="../images/update-logo.png" width="80%" style="display: block; margin: auto;" /> --- # Edit content Mouse to `content/` and: - Edit your `about.md` - [Awesome slide deck here](https://docs.google.com/presentation/d/1pt8eXaGkFH8JTfOjcyvqt1n6DsUs5bSMuHy_NxepMfQ/edit#slide=id.p4) - Example 1: [Julia Silge](https://juliasilge.com/about/) - Example 2: [Kara Woo](https://karawoo.com) - Example 3 (a bit longer): [David Robinson](http://varianceexplained.org/about/) - Example 4: [Emily Robinson](http://hookedondata.org/about/) - Example 5: [Yihui Xie](https://yihui.name/en/about/) - Example 6: [Chester Ismay](http://chester.rbind.io/about/) -- - Edit your `home.md` - We'll make this your new landing page, so imagine this is what people will initially see when they visit your site. - Example 1: [Hadley Wickham](http://hadley.nz) - Example 2: [Sam Tyner](https://sctyner.github.io) --- class: inverse, middle, center ## Take 5 minutes to edit your content  --- # Success? <img src="../images/about-ada.png" width="80%" style="display: block; margin: auto;" /> --- class: inverse, middle, center # 🏇 ## Now we override! --- # Let's override the home page - Index is default landing page for Hugo -- - Look in your theme's layouts directory (`/themes/cocoa-eh-hugo-theme/layouts`). - Open `index.html`- this is the layout for your current home page. -- - Make a *copy* of this file. -- - Put the *copy* in the analogous project root directory: `/layouts/` - It *must* be named `index.html` --- # Edit the `index.html` *copy* - Edit the version in `/layouts/` - *not* `/themes/cocoa-eh-hugo-theme/layouts` -- - We'll remove the latest posts and best posts sections: -- ``` {{ partial "header.html" . }} <div class="main column"> <div class="container"> <div class="content"> {{ range where .Data.Pages "Title" "Home" }} <div class="markdown"> {{ .Content }} </div> {{ end }} </div> </div> </div> {{ partial "footer.html" . }} ``` --- # Success? <img src="../images/ada-home.png" width="80%" style="display: block; margin: auto;" /> --- # Workflow<sup>*</sup> - 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 .footnote[ [\*] From Yihui: https://slides.yihui.name/2017-rmarkdown-UNL-Yihui-Xie.html#30. ] --- # Theme examples - [Julia Silge](https://juliasilge.com) - [Joshua Rosenberg](https://jrosen48.github.io) --- # Blogdown resources - [Blogdown demo site](https://blogdown-demo.rbind.io) - [Blogdown book](https://bookdown.org/yihui/blogdown/) - [Alison 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) --- # Next up! We'll connect to GitHub and deploy to Netlify. --- ## What is hard about `blogdown`? - A lot! - (Sometimes) TOML in `config` file, but YAML in posts - Themes vary a lot - Overriding versus editing directory structure - Related to ⬆️, you have to learn Hugo (in addition to `blogdown`) - For much customization, you'll also have to be comfortable with [CSS](https://bookdown.org/yihui/blogdown/css.html) - [File paths!](https://blogdown-demo.rbind.io/2018/02/27/r-file-paths/) --- ## What is _awesome_ about `blogdown`? - A lot! - Flexibility! - Lots of types of sites, one set of tools - Reliability! - Once you get it working, it will stay that way! - Integration with R!