April 9, 2018

Spinning Up a Hugo Blog /2

Part 2: Installing Hugo

Intro

Alright, so you’re excited about creating your new website and you’re excited to give Hugo a try. Fair enough! Let’s jump right into it!

A couple things to note, though, before we get started. If you are looking for the simplest and quickest way to get Hugo up and running, look no further than Hugo’s own docs. They are fairly easy to read, and are great if you’re just looking to get into it as quickly as possible. For me, quick start guide only got me so far, left me with a lot of questions, and didn’t actually work. My goal here is flesh out some of those questions, as well as provides answers for some of the issues I ran into, just in case someone else does.

It’s also worth noting that while I work on Windows, macOS, and Linux, I’ve only used Hugo on Linux, so that’s what you’ll see here. If you’ve got another OS, things shouldn’t be too different (depending on what you’ve got installed), and Google should be able to get you to where you need to go.

Installation

Installation with Hugo is (mostly) a breeze. Following the instructions on their quick start guide seems to work pretty well, with one caviat that I found-more on that later.

To start off, open your terminal/console of choice. I use the built-in terminal that comes with Ubuntu, my Linux flavor of choice. Using the built-in terminal on macOS should work just as well, though I believe you need Homebrew installed. Windows users will want to follow the steps mentioned here. Once you’re in your console, make sure that you’re not in the wrong folder by typing:

~$ cd

Now, on Linux all you have to do is type:

~$ sudo apt-get install hugo

This should do it for Ubuntu/Debian users. Go ahead and follow the instructions in their docs if you’re using a different operating system.

Once complete, go ahead and type: hugo version to double check that the installation worked. It should show something like this:

hugo version return

The Version Problem

One of the issues I ran into with Hugo was with installation. Or rather, it was with installing a theme. That in itself is an easy enough task, but if you look at a theme here, you’ll see that on the left-hand side, it shows a minimum Hugo version. This is the minimum version of Hugo that you need installed in order to use that particular theme.

That’s all well and good, but installing Hugo by following the instructions in their docs should install the latest stable version, so that any theme can be used, right? Wrong. When I installed Hugo using the apt-get command, it installed version 0.16, or something like that. This only allowed me to use a small handful of themes, and there is no way to sort them by minimum version support.

After some digging, I found that you can manually install the latest and greatest Hugo version by using the appropriate link from this page. This is pretty typical for installing stored on GitHub, but as someone who is fairly new to all of this, it was a bit confusing and frustrating.

To do this (again, on Ubuntu Linux), simply right-click the appropriate link, in my case the one that ends with Linux_64bit.deb, and put the following in a fresh console:

~$ sudo wget https://github.com/gohugoio/hugo/releases/download/v0.37.1/hugo_0.37.1_Linux-64bit.deb

Obviously replace that long url with the one you just copied. By the way, if you’re like me, you’re probably wondering how to paste something into a terminal. Well, usually it’s ctrl+shift+v. Now that we’ve downloaded the newest release of Hugo, let’s unpack it using the following:

~$ sudo dpkg -i hugo*.deb

Now, running hugo version should return the version number that you just installed.

If you’re still not seeing the right version of Hugo, I recommend turning to the good people of the internet to help solve the issue, but if you’re on Linux, and you followed all the above steps, you shouldn’t really have any issues.

Creating Your Site

Now it’s time to create your site. With Hugo, this is very, very easy. It actually only takes a single command. But before we do that, let’s make sure you’re putting that site where you want it!

Create a folder where you want the site to be either in a finder/explorer window, or in your console. Either way, you’ll need to navigate to that folder in your console, so I find it’s easier to just mkdir there. If you’re new to the console and aren’t sure how to navigate, here’s a decent resource to get you started.

Keep in mind that when you create your site, it will create it within a folder with the name of… well, whatever you name your site. So, if you’re making a blog site and you want it to be within your Documents/sites folder, just stay in the sites folder. No need to create one called blog.

Once you’re inside the folder you want to store the site in, we’ll use the following command:

hugo new site blog

Instead of blog, use whatever name you want to identify your site. This will create a new folder with all of the necessary files. So, if we type ls you should see your new site folder listed.

showing list of files/folders in a terminal window

That’s it.

“Installing” a Theme

For most themes, to install, you’re really just going to clone a GitHub repo into your themes folder. So, first things first, cd into your site folder. In my case that would be

cd blog

Now, go to the hugo themes site, and pick one. Remember how I made a big deal about how apt-get install hugo didn’t install the latest version? That’s because most of these themes will require a much later version of Hugo than what it initially installed.

Anyways, pick a theme-I really like Kiss for a super simple blog-and click on the Download button.

where to download a Hugo theme

You’ll want to look for the big green “Clone or Download” button on the themes GitHub page. Click that, and then copy the URL.

download github button

Now go back to your console.

First, we need to initialize Git in your site folder. It’s pretty simple, just git init. If you don’t have Git installed, go ahead and install it first. Then, we want to tell Git to clone and download the theme files into the appropriate folder. By telling it to put the theme in themes/kiss it will automatically create the folder for me.

git submodule add https://github.com/ribice/kiss.git themes/kiss

Let it do its thing. It should look something like this.

installing a Hugo theme

Once that’s done, you’ve pretty much installed a theme. You’ll need to tell your site to use the theme, especially if you have multiple themes installed (which you can totally do). The first thing you’ll want to do is add the theme to your config.toml file. This is where a lot of basic information for your site will go. Being a .toml file, it’s a sort of database for Hugo to pull information from when it’s building your site later on. Once you’ve downloaded and decided on a theme, go ahead and add it to your config.toml file: theme = "themeName".

If you’ve installed multiple themes, and you want to try some different ones, you can use -t to tell Hugo which theme to use when building your site. In a bit, we’ll go over how to view your site on Hugo’s built-in local server, which is a great way to view and try different themes locally.

Adding Some Content

Right now, you’ve got a site with a theme, but nothing else. Let’s make a new blog post to test out how the site looks.

hugo new posts/test.md

This tells Hugo to create a new post called test.md. .md files are Markdown files. Markdown is a great way to quickly and easily write content for the web. It has it’s own, simple, syntax, and then Hugo will spit that out at HTML in your site files. It’s worth learning a bit of Markdown to make writing your posts easy (and honestly quite fun).

Go ahead and open your new Markdown file in your favorite text editor. It will be in the posts folder within your site folder. The first thing you’ll see is a bit of metadata that Hugo automatically added to the top of the file. For now, let’s just leave that as-is.

Go ahead and add some text underneath that metadata-after the second set of dashes-and then save the file.

Congrats! You just added some content to your site!

Viewing the Site Locally Using Hugo Server

Head back over to your console, and make sure that you’re in your site folder. If you’ve done everything the way I’ve described, you should already be there, but it never hurts to make sure. Whenever you’re working on your site, and you want to view it in the broswer locally, you’ll use the Hugo server. This is the built-in local server that comes with Hugo, and it makes it super easy to build and view your site with one simple command.

hugo server

That’s it.

Now you can go to http://localhost:1313/ to view your site. However, if you left the metadata on your test.md file alone, you’re probably not seeing that post. That’s because Hugo creates a new post as a draft by default, and running the server normally will ignore drafts. To see your drafts as well, all you have to do is add -D after the server command. First, cancel the current instance of the server using ctrl+c. Then:

hugo server -D

Now you should be able to refresh the site and see your post! It will likely say “:Draft” after it, letting you know that it’s a draft.

To view your site with different themes, simply do like this:

hugo server -t themeName

Fun fact: Hugo server has an auto-refresh feature, so if you make a change to your posts while it’s running, your changes will appear as soon as you save the file. No need to refresh! It’s pretty great, but I have had instances when I needed to refresh the page a few times to see a bigger styling change or the like.

Go Have Fun!

From here, go ahead and play around! If you want to do something specific with the site, Hugo’s own docs are a great resource, but there are plenty of people out there who know what they’re doing, and more than willing to help.

Hosting Your Hugo Site Online

Simply run the hugo command within in your site folder to build the site. This will create a folder called public, which contains all the normal site files in .html, .css, etc.

There are various ways to host a Hugo site. I personally host mine on GitHub Pages. I found this guide to be extremely helpful for getting that working (along with a lot of trial and error). You could upload files via ftp. Whatever you feel comfortable with.


I hope that you’re finding as much joy in building with Hugo as I have. It’s allowed me to quickly, easily, and enjoyably build static websites, even on a busy schedule. I can’t wait to build something else!

© Chris Colvin 2018