Up and running with blogdown, GitHub, Netlify, and tranquilpeak

Blog
R
Published

April 6, 2018

I am primarily a MacOS user who does most of my analytics and presentation work in R / RStudio / RMarkdown, so it was natural to take advantage of using the R blogdown package.

Many others have already documented nice tutorials on how to get a blog started with blogdown, Hugo, GitHub, and Netlify, so I’ll just reference a number of resources that I found particularly helpful. Also, I chose to use the tranquilpeak Hugo theme, as I liked the look of it, and it generally seems to play well in this environment.

Recipe for getting started

  • Up and running with blogdown by Alison Presmanes Hill
    • a remarkably clear set of instructions on getting started with blogdown, GitHub, and Netlify

Other helpful resources

  • [Making a Website Using Blogdown, Hugo, and GitHub pages] (https://amber.rbind.io/blog/2016/12/19/creatingsite/) by Amber Thomas
    • a little more dated, and not exactly the approach I chose, but still very helpful
  • Blogdown and Tranquilpeak Hosted on Netlify: a Deep Dive by Bryan Whiting
    • another quick, straightforward tutorial
    • included a bit about how to have a static About page in the tranquilpeak theme

Steps for setting up

I pretty much followed the steps described by Alison Presmanes Hill, with a few minor changes and tweaks.

  • Created a {{< hl-text red >}}GitHub{{< /hl-text >}} repository (private)
    • initially I planned to make it Public, but because I’m often analyzing clinical datasets, I didn’t want to risk accidentally exposing protected health information
  • Developed in {{< hl-text red >}}RStudio{{< /hl-text >}}
    • installed {{< hl-text red >}}blogdown{{< /hl-text >}} and {{< hl-text red >}}Hugo{{< /hl-text >}}
    • created a {{< hl-text red >}}blogdown::newsite(){{< /hl-text >}} using the {{< hl-text red >}}tranquilpeak{{< /hl-text >}} theme
  • Deployed with {{< hl-text red >}}Netlify{{< /hl-text >}}
    • by default {{< hl-text red >}}Netlify{{< /hl-text >}} builds with hugo_0.19, but {{< hl-text red >}}tranquilpeak{{< /hl-text >}} requires hugo_0.20
    • no worries – it’s easy to choose a different version
    • set Build command to just hugo
    • set the Build environmental variable of HUGO_VERSION to 0.38.1
  • Obtained a domain name

Additional tweaks and discoveries

  • Custom blog post summaries on the index page don’t work in posts built from {{< hl-text red >}}Rmd{{< /hl-text >}} (at least for the tranquilpeak theme)
    • In markdown posts, all text above <!--more--> are used for the post summary on the index page
    • However, this doesn’t work for Rmarkdown posts
    • Instead, it’s possible to modify the theme to be able to specify a custom summary in the YAML header
  • Most methods of syntax highlighting don’t seem to fully support R code
    • best solution so far seems to be to use the highlight tag, which might be specific to {{< hl-text red >}}tranquilpeak{{< /hl-text >}}

The following (remove the space between the {’s, as I can’t figure out how to escape the {):

{ {< highlight r >}}
library(tidyverse) # a comment
x <- mean(mtcars$mpg)
{ {< /highlight >}}

Becomes:

library(tidyverse) # (this was only with tranquilpeaks, not relevant otherwise)
x <- mean(mtcars$mpg)