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

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 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
  • installed and
  • created a using the theme
• Deployed with
  • by default builds with hugo_0.19, but 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
  • followed Netlify’s instructions on using a custom domain
  • with just a few clicks, Netlify also obtains a Let’s Encrypt certificate and forces SSL

Additional tweaks and discoveries

• Custom blog post summaries on the index page don’t work in posts built from (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

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)

• when I have more content, I’d like to be listed on R-bloggers, but they require RSS feeds with full content and not just the Summary. I followed these directions to override site-wide the rss.xml to include full content. I obtained the RSS template from the Hugo documentation.