1 Read up on blogdown

Before you start, I recommend reading the following:

• blogdown: Creating Websites with R Markdown by Yihui Xie and Amber Thomas
• Making a Website Using blogdown, Hugo, and GitHub pages also by Amber Thomas

I also found this comment by Eric Nantz, the creator of the R-Podcast, in the rbind/support issues section on GitHub to be helpful:

• https://github.com/rbind/support/issues/12

2 Caveats, disclaimers, etc.

Even with all the great resources I listed above, getting myself up and running took a few tries, so in this post I’m passing along what ended up working for me. Everyone’s mileage may vary, though, depending on your operating system and your approach. About me: I am a macOS user, and I use R, RStudio, Git (usually via GitLab, sometimes via GitHub), and terminal regularly, so I’m assuming familiarity here with all of these. If that is not you, here are some places to get started:

• For Git: Happy Git with R by Jenny Bryan et al.
• For RStudio: DataCamp’s Working with the RStudio IDE (free) by Garrett Grolemund
• For Terminal: The Command Line Murder Mystery by Noah Veltman, and The UNIX Workbench by Sean Kross

I also have Xcode and Homebrew installed- you will probably need these to download Hugo. If you don’t have either but are on a mac, this link may help:

• How to install Xcode, Homebrew, Git, RVM, Ruby & Rails on Mac OS X

Finally, I did not want to learn more about a lot of things! For instance, the nitty gritty of static site generators and how domain names work. I am a new mom, and just in the process of writing all this up, I filled up my tea mug twice with ice cold water, and filled my water bottle with scalding hot water. So, where offered, I followed the advice of Yihui and Amber. For example:

• “Considering the cost and friendliness to beginners, we currently recommend Netlify.” Sold.
• “If you are not familiar with domain names or do not want to learn more about them, an option for your consideration is a free subdomain *.rbind.io offered by RStudio, Inc.”. Done.

3 In GitHub

1. Go online to your GitHub account, and create a new repository (check to initialize with a README but don’t add .gitignore- this will be taken care of later). For naming your repo, consider your future deployment plan:

   • If you are going to use Netlify to host the site, you can name this repository anything you want!
     You can see some of the repo names used by members of the rbind organization here.
   • If you want to host your site as a GitHub Page, you should name your repository yourgithubusername.github.io (so mine would have been apreshill.github.io). If you are going this route, I suggest you follow Amber’s instructions instead of mine!

Screenshot above: Creating a new repository in GitHub

2. Go to the main page of your new repository, and under the repository name, click the green Clone or download button.

3. In the Clone with HTTPs section, click on the clipboard icon to copy the clone URL for your new repository. You’ll paste this text into terminal in the next section.

4 In terminal

Now you will clone your remote repository and create a local copy on your computer so you can sync between the two locations (using terminal or your alternative command line tool for a Windows machine).

1. Use cd to navigate into the directory where you want your repo to be

2. Once there, type: git clone [paste]. So my command looked like this:

git clone https://github.com/apreshill/apreshill.git

And this is what printed to my terminal window:

Cloning into 'apreshill'...
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.
Checking connectivity... done.

3. Close terminal, you are done in there.

5 In RStudio

1. Install blogdown from your RStudio console. If you already have devtools installed like I did, you can just use the second line below:

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

2. Install Hugo using the blogdown package helper function:

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

3. Use the top menu buttons in RStudio to select File -> New Project -> Existing Directory, then browse to the directory on your computer where your GitHub repo is and click on the Create Project button.

Screenshot above: Creating a new project in an existing directory in RStudio

4. Now you should be “in” your project in RStudio. If you are using git for version control, edit your *gitignore file. This file should be viewable in your file viewer pane in RStudio. Below is what it should look like: the first four lines will automatically be in this file if you have set up your RStudio Project, but if you plan to use Netlify to deploy, you need to add the public/ line (read about here.)

.Rproj.user
.Rhistory
.RData
.Ruserdata
blogdown
.DS_Store # if a windows user, Thumbs.db instead
public/ # if using Netlify

6 Build your site in RStudio

Now you can finally build your site using the blogdown::new_site() function. But first you should at least think about themes…

blogdown::new_site() # default theme is lithium

# for example, create a new site with the academic theme
blogdown::new_site(theme = "gcushen/hugo-academic", theme_example = TRUE)

library(blogdown)
new_site() # default theme is lithium
# need to stop serving so can use the console again
install_theme("gcushen/hugo-academic", theme_example = TRUE, update_config = TRUE)

baseurl = "https://example.com/"
baseurl = "/"

Started building sites ...
ERROR 2017/06/08 16:22:34 failed to parse page metadata for home/about.md: (18, 6): missing comma
Error: Error building site: Errors reading pages: Error: failed to parse page metadata for home/about.md: (18, 6): missing comma for about.md

blogdown::new_post()
blogdown::new_post(ext = '.md') # md is the default!

new_post(title, kind = "", open = interactive(),
    author = getOption("blogdown.author"), categories = NULL, tags = NULL,
    date = Sys.Date(), file = NULL, slug = NULL,
    title_case = getOption("blogdown.title_case"),
    subdir = getOption("blogdown.subdir", "post"),
    ext = getOption("blogdown.ext", ".md"))

blogdown::new_post(ext = '.Rmd') # md is the default!

---
title: "My Awesome Post"
author: "John Doe"
date: "2017-02-14"
output:
  blogdown::html_page:
    toc: true
    toc_depth: 1
    number_sections: true
    fig_width: 6
---

![my-image](/img/my-image.png)

7 Deploy in Netlify

Deploying in Netlify through GitHub is smooth. Yihui and Amber give some beginner instructions, but Netlify is so easy, I recommend that you skip dragging your public folder in and instead automate the process through GitHub.

1. When you are ready to deploy, commit your changes and push to GitHub, then go online to Netlify.

2. Click on the Sign Up button and sign up using your existing GitHub account (no need to create another account)

3. Log in, and select: New site from Git -> Continuous Deployment: GitHub.

4. From there, Netlify will allow you to select from your existing GitHub repositories. You’ll pick the repo you’ve been working from with blogdown, then you’ll configure your build. This involves specifying two important things: the build command and the publish directory (this should be public).

   • More about the build command from Netlify: “For Hugo hosting, hugo will build and deploy with the version 0.17 of hugo. You can specify a specific hugo release like this: hugo_0.15. Currently 0.13, 0.14, 0.15, 0.16, 0.17, 0.18 and 0.19 are supported. For version 0.20 and above, you’ll need to create a Build environment variable called HUGO_VERSION and set it to the version of your choice.” I opted for the former, and specified hugo_0.19.

You can check your hugo version in terminal using the command hugo version. This is what my output looked like, so I could run version 0.20 if I wanted to through Netlify, but I went with 0.19 and it works just fine.

$ hugo version
Hugo Static Site Generator v0.20.7 darwin/amd64 BuildDate: 2017-05-08T18:37:40-07:00

Screenshot above: Basic build settings in Netlify

Netlify will deploy your site and assign you a random subdomain name of the form random-word-12345.netlify.com. Mine was particularly unfortunate, with the random word garbage-collector-janice. You should know that you can change this; I changed mine to apreshill.netlify.com.

At this point, you should be up and running with blogdown, GitHub, and Netlify, but here are some ideas if you want to go further…

8 Going further

  # Link custom CSS and JS assets
  #   (relative to /static/css and /static/js respectively)
  custom_css = ["blue.css"]

<form action="https://formspree.io/your@email.com" method="POST">
  <label for="name">Your name: </label>
  <input type="text" name="name" required="required" placeholder="here"><br>
  <label for="email">Your email: </label>
  <input type="email" name="_replyto" required="required" placeholder="here"><br>
  <label for="message">Your message:</label><br>
  <textarea rows="4" name="message" id="message" required="required" class="form-control" placeholder="I can't wait to read this!"></textarea>
  <input type="hidden" name="_next" value="/html/thanks.html" />
  <input type="submit" value="Send" name="submit" class="btn btn-primary btn-outline">
  <input type="hidden" name="_subject" value="Website message" />
  <input type="text" name="_gotcha" style="display:none" />
</form>