Syllabus • blogdown.website.intro

Hao Ye Health Science Center Libraries, University of Florida (updated: 2022-07-19)

Intro

Motivations
- You would like a professional-looking website to present yourself.
- You don’t want to spend time/money designing something completely custom.
- You want to use or learn github / blogdown.
- You want to make blogposts using R Markdown.
Prerequisites This lesson assumes you:
- have some familiarity making repos and commits
- know how to synchronize repos from your computer to GitHub Such as via https://uf-repro.github.io/friendly-github-intro/
Learning Outcomes By the end of the workshop, participants will be able to:
- create a basic website using Blogdown
- host a website on GitHub Pages
- describe the workflow for continuous deployment
- deploy a Blogdown website using GitHub Actions

Setup

Required Packages

install.packages(c("usethis"
                   "blogdown", 
                   "renv"))

These packages and their included dependencies will have all the tools that we need to get started.

Git and RStudio RStudio is not required, but does make some steps easier, so I strongly recommend it. If you have not yet configured Git and GitHub for use from within RStudio, check out these guides:
- “Happy Git and GitHub for the useR”
- “Managing Git(Hub) Credentials”
Install Hugo Hugo is a static site generator that we will use. This code from the blogdown package will install the latest version and make it available to us.
```
blogdown::install_hugo()
```

Creating a new site

Choose a name The address will be https://{username}.github.io/{repo} e.g. for my username ha0ye and repo my-site, the eventual website address will be https://ha0ye.github.io/my-site/ You can also host at https://{username}.github.io/
- choose {username}.github.io as the repo name.
New RStudio Project
1. Open RStudio.
2. File -> New Project
3. Select New Directory
4. Use the name previously chosen, set the local directory, and Create Project.

Create Blogdown Site

blogdown::new_site(
    theme = "hugo-apero/hugo-apero", 
    format = "toml",
    sample = FALSE,
    empty_dirs = TRUE)

Set baseURL Open config.toml. There are a number of configuration options here. Right now, set baseURL to the eventual URL of your site. For example:
```
baseURL = "https://ha0ye.github.io/blogdown-demo"
```
Activate renv The renv package will capture all the needed packages to build our website and record this information in configuration files that GitHub will use.
```
renv::init()
```
Setup GitHub Actions We need to give GitHub instructions on how to build our website, and there is a premade script for us to use.
```
usethis::use_github_action("blogdown")
```
Commit and Push These commands will enable Git for this project, and then push it to a new repo on GitHub.
```
usethis::use_git()
usethis::use_github()
```
Demo

Technical Machinery

Hugo Hugo is a static site generator. (there are many other applications that do similar things) It combines your content with a set of theme/style files to create a static HTML webpage. You can create content in markdown, and not worry about styling.
Blogdown The {{blogdown}} package combines R Markdown and Hugo.
- you can author pages using R Markdown (so you can create code examples)
- it uses Hugo, so you have access to any Hugo theme.
Blogdown Preview In your website project, you can preview the webpage with
```
blogdown::serve_site()
```
- You can pop out the panel from RStudio to your web browser.
- It will re-render when you save changes.
GitHub Pages GitHub Pages will host websites from github repos for you, in the github.io domain. GitHub Pages can also render using Jekyll, but we are ignoring it for now. For GitHub Pages to work, we need to specify where the website files are. We choose the gh-pages branch, where only the rendered web files will be stored.
GitHub Pages Configuration In the GitHub page, navigate to “Settings”
GitHub Pages Configuration then select “Pages”
GitHub Pages Configuration then select the “gh-pages” branch as the source and click “Save”.
GitHub Actions GitHub Actions lets us do workflow automation on GitHub. Our provided script will setup an R environment to build our website, and then put the website files into the gh-pages branch. This means, when we update the contents in GitHub, it will render and update the website automatically.
Workflow Suggested website workflow:
1. Open the RStudio project for your website.
2. Start live previews with blogdown::serve_site()
3. Make changes to the website
4. Commit changes and push to GitHub.
Demo

Customization

Menus config.toml also determines the top-level menu of your website and what the links are. You can customize the links, including adding your own or removing the defaults. See the doc page for more information.
Static Files Files that you want accessible to your website, but not processed through Hugo should go in the /static/ folder.
- it is common to put images in /static/img/.
- The file /static/img/image.jpg becomes https://ha0ye.github.io/blogdown-demo/img/image.jpg on the website.
Fonts and Colors You can choose from among the theme’s built-in fonts and colors by editing config.toml. Customization is available, but will require you to go to extra effort to specify the exact colors and fonts to use. See the doc page for more information.
Demo

Content

Basics The contents of the website are determined by the files in the content/ folder. Each folder corresponds to a section of the website, and has a page that can be linked. For example, the about/ folder contains files to create the https://ha0ye.github.io/blogdown-demo/about page.
Sections Each section has a _index.md file that contains metadata about how the section will be formatted, and sometimes some descriptive text. This information is in a yaml section at the top of the markdown file that begins and ends with
Pages Within each section, individual pages can be individual markdown files, or folders with an index.md file.
Styling There are built-in layouts that determine how a page is formatted. You can set this in the layout: field in the YAML header. For more info, see the examples in the template or the docs on
- section configuration
- page configuration
Demo
Themes
- This guide used the Hugo Apéro theme, but many are available!
- You can choose a different theme when making a site, or use blogdown::install_theme()
- more themes can be found at https://themes.gohugo.io/
Custom Domains
- You can use an alternative host rather than GitHub Pages.
- A common tool is to use Netlify to build the website.
  - Netlify will assign a random subdomain of the form *.netlify.com
  - You can use a custom domain with Netlify. (Namecheap is a commonly recommended store.)
Summary
- A combination of tools and platforms can get you up and running with a personal website quickly!
  - blogdown + GitHub Pages
- Customization is possible! (but not always easy) ## Thanks
Let me know what content you’d like to see
Contact me for additional questions or consultation requests!
Check back in on the libguide for more modules and contact info:
- https://guides.uflib.ufl.edu/reproducibility