Creating a website with Blogdown/Hugo

Tips for beginners creating a website with Blogdown/Hugo 👍

Last updated on Apr 17, 2019 9 min read

**This post is for those interested in creating a free website using Hugo and Blogdown. Read on for tips to easily make your own website.**

A bit of background…

I’m not an expert in R, html, or [insert any other language], but I am really good at Googling things… so that’s where I started when creating my website. There are a lot of really helpful resources out there (see here, and here) for getting started with website creation using Blogdown and Hugo. However, despite these amazing tutorials, I still had to deploy expert Googling skills to work through a few snags. This post is not meant to replicate the wonderful tutorials others have already created. Rather, it’s meant to just slightly expand some explanations for those of us who need a bit more detail.

Disclaimer: The words written here are just reflective of my own experience. Your experience may be quite different, but my hope was to try and bring to light a few of the hurdles I faced and the work arounds I found. I used GitHub and deployed with Netlify so that’s what the below ‘tips’ reflect. It’s also a working document so pictures and a more aesthetically pleasing layout to come soon. No judgement.

I will create another post on how I made my course websites. Similar process (Hugo/Blogdown) but a different theme and thus a slightly different approach.

Getting Started

Before starting, I highly recommend reading chapters 1 - 3 of the amazing book Creating Websites with R Markdown by Yihui Xie, Amber Thomas, and Alison Presmanes Hill. It’s really well written and it provides some essential background information that will make your life much easier (and save you some Googling time).

A few things I got stuck on with Installation

I already had R and RStudio working and had been using them for years, but I wanted/needed to install Git for other things I was working on. This turned out to be a problem for me.

Installing Git for Windows in RStudio

ok – this one really threw me for a loop. I installed Git and suddenly RStudio crashed and wouldn’t do anything. I panicked (like one does) and for an entire week I tried absolutely everything…even the dreaded uninstall and re-install of both R and RStudio. Nothing Worked.

Finally, I uninstalled git and magically RStudio worked once more. Problem? – I actually need Git so here is the workaround: * You need to clear your local session state (which doesn’t happen by deleting and reinstalling!). To do this, go to your local RStudio folder. For me this was at:

C:\Users\username\AppData\Local\RStudio-Desktop

_{(where ‘username’ is your individual username)}

Change the name of that folder and then restart RStudio to get it to generate a new folder with a new address to Git.
Then delete the folder you renamed and voila! RStudio and Git should love each other once more. Also, this is small potatoes, but FYI - this does delete whatever preferences/Global options one had set up in RStudio.

Done with installation? Follow Alison’s tutorial!

Next, start with Alison’s very well-written tutorial: “Up & Running with Blogdown” on creating a website.

Additional helpful info as you work through Alison’s tutorial:

Cloning your Github Repo

After you create your Github repo (aka after you complete numbers 1-3 on Alison’s website), you can clone it via RStudio instead of with terminal (so this is an alternative way to #4 on her tutorial). Go into RStudio and do the following:
```
Project --> Version Control --> Git --> *enter your repository URL*
```

_{*Go to your Github repository and click the “clone or download” button to copy the URL}

Continue with #6 on Alison’s tutorial on creating a website.

Picking and personalizing your theme

As is recommended in the Blogdown book and in Alison’s tutorial, I used the Hugo Academic theme. Important to note is that personalizing your website varies depending on the theme so read the documentation!
- For example, personalizing the Academic theme is no longer done with the config.toml file. It’s now done in the menus.toml. Details such as this can be found in the Hugo-Academic Documentation.
- Another example of a theme is Jonathan Gilligan’s Hugo-Syllabus template (Github code and Example), and configuration of this template is done in the config.toml file.
When you create the menu buttons on the front of the website (either through the config.toml or the menus.toml or whatever file it’s on), you will then create a markdown (.md) (not R Markdown) file in the content directory to populate that button (e.g. have words, etc appear on a page when that button is selected). See the section below ‘Creating a new post’ for how to do that.
Note Your newly created file name must match the menu name that you chose in your configuration file (e.g. config.toml or menus.toml)

Bottom Line:

Read the documentation for the theme
Download the example (if available) for the theme to see how things work
Look on Github at the repositories and configuration files for people who have used that theme

Creating a new post

If you want to create a new new post (and by ‘new post’, I mean any new markdown or R Markdown document), you go into the Addins menu and select new post.
To specify where that post will go (i.e. into what folder), specify that in the subdirectory section. For example, you could type this into the subdirectory section of the new post box to put your new post in the “Getting-started” folder:

_{yes… I will take a screen shot at some point to make this easier}

If you forget to specify the directory, no problem. Just save it wherever and then move it manually (through your finder folder) or use the Files tab in RStudio (check the box –> more and then move to)

Continue on with Alison’s tutorial until you get to # 7 “Deploying with Netlify”.

Deploying with Netlify

So… Netlify will only be able to deploy your site if the version of hugo you’re running matches with what they are using to deploy. Since Alison’s blog post, the way to do this is a bit different, but still very easy. Here’s how to do it:

Push all the changes you’ve made to Github I had a few problems with RStudio crashing when I tried to stage and push things to github so here is a workaround. In the termial window, type the following:
- git add -A
- git commit -m “enter your commit message here“
- git push origin master

To push things individually, you can check the box under staged in the Git window of RStudio and commit that way.

Then go to github and make sure it’s all there!

Note If you can’t get Git to commit, it means you need to listen to that red warning you received To stop the server, run servr::daemon_stop(1) or restart your R session when you inilized serve_site.
If neither of those options work, go into your .git folder (in your repository folder on your personal computer) and delete the index file.

Go to Netlify and log in with your github account
Click New site from Git and choose your Git provider (mine is GitHub)
Select the repository of choice and click deploy site
If you get an error, it’s probably because of your Hugo version.

First, figure out what version of Hugo you have
Then, read this workaround
- Important to note is that in order to edit variables in Netlify now, things are a bit different than when Mara wrote that tutorial. Now, within Netlify, go to:
```
Build and Deploy --> Environment --> Edit variables
```

Using a custom domain name

Netlify automatically gives you a webite name (mine was something like zealous-aardvark). You can change this name to whatever you want (e.g. jenniferbradham.netlify.com). However if you want to use a custom domain name (e.g. jenniferbradham.org), then you have a few more steps to do. I purchased my domain name through Google Domains, so that’s what I’ll be referencing in the steps below.

Here is the Netlify manual on how to add a custom domain. For simplicity’s sake, I’ll outline the relevant steps below, but the tutorial provides a lot more information.

Deploy your site with Netlify (see above)
Log in to Google Domains, and select the name of your domain (if you just have one domain, then there is only one option).
In the left navigation panel, click DNS
Scroll down to Custom resource records. Here you will create two entries. This is all in the Netlify custom-domains manual, under the heaing “Manual DNS Configuratiion for Root and WWW Custom Domains”.
```
Name      Type        TTL     Data
@         A           1H      104.198.14.52
```

and the second entry is:

Name      Type        TTL     Data
www       CNAME       1H      yournetlifysitename.netlify.com

Go back to Netlify, select the Domain management tab then click the link next your custom domain. The link will say something like “verify with Netlify”. Click that link and follow the instructions. Netlify will then instruct you to enter the custom name servers.
- To do that go back to your Goolge Domains page and look under the Name servers selection (again, under the DNS tab).
- Select Use custom name server and enter each of the numbers provided by Netlify as a separate entry.

Shortcodes

While looking at other people’s configuration files on GitHub, you may come across something that looks like this:

That is referencing a Hugo shortcode. Here is a great tutorial on using shortcodes and here is one on writing your own shortcodes.

One thing to note is that shortcodes are written in html. You can’t create an html document with the New Post function in Blogdown. Instead just use a text editor (e.g. notepad on Windows) and save it as html in the shortcodes folder that you will create within the layouts folder. Below the File name bar, make sure you change Save as type from *.txt to All Files (*.*) so your file doesn’t have a .txt ending.

Additional helpful links

_{I’m basically using this section so I can easily get back to links I often need}

Here is a helpful link on getting started with Hugo in general
Updating you version of Hugo for blogdown on Netlify
Markdown Cheatsheets
Git ignores directories with no contents so don’t panic if it shows up gray in your git repository
One more tutorial that might be helpful
Inserting an image into your post
My layouts folder disappeared
Relative links
Markdown extended syntax
Changing icons on your webpage