Blogdown and Tranquilpeak Hosted on Netlify: a Deep Dive
This blog will outline what I see as differences between Hugo and Jekyll, some benefits and drawbacks of using Netlify vs. GitHub pages to host, and how to launch the Hugo Tranquilpeak theme from scratch.
One of my first posts was about blogging with Jekyll hosted on GitHub. About six months after writing that post, I hit a few bugs trying to debug it and got frustrated because I had already forgotten all of what I binge-learned earlier. I was tired of re-updating my Jekyll code, and ultimately gave up since I didn’t use it often enough. And so I switched to Hugo and blogdown. Here are the reasons why I’ve already switched from Jekyll to Hugo:
- Jekyll requires you to download and manage the software which caused me a lot of headaches and debugging. Blogdown manages all of the Hugo installations for you.
- I wanted to be able to use R Markdown in my blogs and Jekyll doesn’t have a native integration. Andrew Brooks has a solution that allows you to use R Markdown and Jekyll, though I had trouble using it1.
- Netlify allows HTTPS for custom URLs, whereas GitHub only allows HTTPS for
username.github.iopages (not custom URLs). Here’s a discussion on GitHub pages v. Netlify.
- Configuring a custom URL on Netlify is extremely easy compared to GitHub pages. (If you don’t use a custom URL, you won’t like the one Netlify provides by default.)
blogdown is an R package that manages the Hugo software, which is a static website generator. Here’s the package on GitHub, which has a handy 5 min instruction to get your feet wet. Here’s the official tutorial on blogdown and is a great resource.
You will spend some time getting to know blogdown and Hugo, and Hugo requires as much work figuring out as does Jekyll if you want to get into the gritty customization. That being said, blogdown makes it easy to get started and come back several months later without having to worry about managing all of the Jekyll packages.
A few things about blogdown and Hugo I’ve learned:
- Hugo is a static site generator (meaning it makes a very basic website)
- Hugo is software you download and run to build and compile your website
- blogdown is a wrapper for Hugo terminal commands
- blogdown renders R Markdown files (Hugo can’t)
- blogdown automates installing everything you need for Hugo. (This was very difficult to do with Jekyll at first.)
- blogdown runs the Hugo commands to compile your site locally
serve_site()lets you edit your posts and view the changes simultaneously with every save
build_site()prepares the site for production
blogdown for Tranquilpeak theme
Every Hugo site is different, and each has a different config file. So I’ll go step by step on how I launched my blog.
Launch your website in 5 minutes locally
install_hugo()to get the latest version. You may have to update Hugo periodically, as it’s open source and keeps updating. So if you’re having issues building your site, try debugging using
install_hugo(force = T).
new_site()command to build a website from scratch. (Note, these two steps can save you hours of reading documentation if you go the Jekyll route.)
- Make sure you specify the theme you want, e.g.
new_site(theme = 'kakawait/hugo-tranquilpeak-theme'), because it’ll download the right
config.toml. Here’s a note from the docs:
...You need to be very careful when changing themes, because one theme can be drastically different with another theme in terms of the configurations. It is quite possible that a different theme will not work with your current config.toml. Again, you have to read the documentation of a theme to know what options are supported or required.
- Now the site is built, you’ll see several folders. The github Hugo theme is saved in
themes. The entire site is saved and compiled in
public. And Blogdown and Hugo do the work of preparing your content and putting it in the
publicfolder. Your posts are in
content, and your images are in
- To get started, put all your blogs in the
content/post, and your site images in
build_site()when you’re ready.
- If you run
new_post(), it’ll create a post in
Host your blog on Netlify
I cover here how to use Netlify to host, which is extremely easy! Here are the steps:
- Put your entire site as a repository on GitHub, Gitlab, or Bitbucket. (I did GitHub.)
- Go to Netlify.
- Connect your GitHub accounts.
New site from Git.
- Continuous deployment: click
GitHub. You can limit access to only public repositories.
- Click on your GitHub blog repo.
- Branch to deploy:
- Build command:
hugo_0.19(See docs on build command)
- Publish directory:
- Branch to deploy:
Deploy site. Netlify will generate a random URL
destiny-jones-84018.netlify.comand launch your site.
Connecting your custom domain
Netlify makes it very easy, more straightforward than GitHub pages to connect your custom domain.
Settings > Configure domain. Just add your custom domain in the space provided and update your DNS configuration. For some reason, this took me forever to figure out on Jekyll and GitHub pages (it seemed like everyone knew how to do this but me…).
Encrypt with HTTPS
If you want, you can encrypt your site with HTTPS, as Yihui recommends. Once your site is deployed, you can click the
HTTPS tab on Netlify and follow instructions.
Disqus is great for comments, but can be confusing to get set up. There are two parts - setting up a Disqus account and site and updating your Hugo
Set things up on Disqus:
- Go to disqus.com and create a profile.
- Click on
- In the top left corner, click
- Under website name, just put something like “data science blog”, or whatever you want to name it.
- It’ll now ask you to connect to a platform. Skip this and go to
3. Configure Disqus.
- You’ll see your website name. Under
Website URL, put the
http://<netlify-name>.netlify.com. (I don’t know if you can put your custom domain here, but for me putting my Netlify URL worked fine.)
- Go to
Settingsand it’ll provide the shortname. Copy that.
- Under baseurl I put my custom URL “https://www.bryanwhiting.com".
Note, Disqus won’t work when you use
serve_site() command. It only works on the live website.
Change the background photo
This took me a minute to figure out, but I learned something about Hugo, so I’ll share it here.
- Put your desired photo in
- Under `[author] picture = yourphoto.png’
You’ll notice in the
public folder, the
static folder doesn’t exist, but
images does (after you
Adding a static About page
I love the Tranquilpeak about popup page, but I wanted to have more than just a 10-word description. Here’s how you add one to the sidebar menu. The blogdown docs explain this.
- Add a file in
- Add the following menu link in
config.toml. Note the default URL connects to
#about, which is defined in
theme/hugo-tranquilpeak-theme/scr/js/about.jsand yields the cool pop-up. When you create
serve_site(), the file
[[menu.main]] weight = 4 identifier = "about" name = "About" pre = "<i class=\"sidebar-button-icon fa fa-lg fa-question\"></i>" #url = "/#about" url = "/about/index.html"
There’s probably a better way to do this, but that’s beyond my current understanding.
Categories and tags
I could use the following YAML to tag this post. Since
"blog" is the second category, it’s considered a subcategory of tutorials. Each blog should fit into only one category, but have multiple tags.
title: 'Blogdown and Tranquilpeak Theme Hosted on Netlify' date: '2017-06-20' author: 'Bryan Whiting' categories: ["tutorials", "blog"] tags: ["blogdown", "r", "hugo"]
Debugging tip: I think you need to have the brackets
for the categories and tags, even if you only have one element. I was getting the error “Error while rendering “page”: template: … <.>: range can’t iterate over …
” when I lacked the brackets
Takeaways and next steps
You’ve got a great blog ready to go! There are things I’d like to add to my Tranquilpeak site, such as a project page (similar to having a second post page). The key to learning how to do that may be documented here.
- Alternatively, I could knit the R Markdown file to HTML and Jekyll could read the HTML file, but each R Markdown post ultimately had a different formatting than the normal markdown posts. [return]