For the last few days, I have been working on setting up this blog site. Keep in mind this is my first attempt at such a thing. I was originally interested a few months ago but kept putting it off due to either laziness or not finding a theme that interested me. I’ve documented the process in the hopes that others may find it helpful. This guide will cover site creation to hosting on Github Pages. Let’s get started:

Installing Hugo and creating a new site

This is perhaps the simplest step, just follow the instructions in their Quick Start guide and we’re half way there already! I’m on a Mac so I installed hugo using brew. I won’t belabor this step, so once you’ve done this we can move forward.

Adding a theme

By now you should have a site ready to go. If you added a theme using the quick start instructions that’s great! Otherwise, once you find a theme you like, just download it, and place it in the themes/ directory. Then in your config.toml references it as such (given my theme’s name is "temple"):

baseURL = "https://aos.github.io/"
languageCode = "en-us"
title = "Awesome Blog"
theme = "temple" <-- Theme goes here

Alternatively, you can clone into into your themes directory:

$ cd themes && git clone https://github.com/aos/temple.git

Or pass it in as a parameter when building the site:

$ hugo -t temple

Adding a blog post

Great! So now we’ve added a theme, but our blog is empty… so let’s create a post. Lucky for us, Hugo does a lot of it for us! The command is:

$ hugo new posts/my-first-post.md

This will create the directory content/posts/ and which will house your new blog post. Go ahead and open the file and edit it. You will notice at the top there will be some info about your post:

---
title: "My First Post"
date: 2017-11-19T16:58:03-05:00
draft: true
---

This is known as the front matter and it will contain some metadata about your post.

When you go to publish your blog, the post will have the link of yoursite.com/posts/my-first-post. If instead you prefer permalinks (like me), add the following line to your config.toml:

[permalinks]
    posts = "/:year/:month/:slug/"

This is configurable, refer here for documentation.

Previewing our site locally

It’s time to reap the fruits of our hard work. Run this command:

$ hugo server -D

It will generate a local server with our drafts (this is the option -D) of our blog post. The server should be accessible at localhost:1313.

If you do not see your post (as it happened to me the first time), it could be because of the theme you chose. Since Hugo is in active development, some older themes may not work properly as the syntax has changed. After digging thoroughly through the documentation, I diagnosed the error. The documentation is inconsistent in that some places reference directories in contents/ with the singular type. If you have an older theme, it will look for the older singular type variable.

Example (themes/<THEME>/layouts/index.html):

{{ if eq .Type "post" }}

The .Type variable now returns the plural form. The simplest fix in this situation is to copy over the file and place it in a matching directory as the root of your blog. Here it would be: <root>/layouts/index.html, then change the .Type variable to plural: "posts".

Another thing to note here, is that on doing this, you might also see your entire Posts directory being displayed as a separate link. To fix this as well, look for something along the lines of this:

{{ range $name, $page := .Site.Pages }}

in the same file and replace .Pages with .RegularPages.

Publishing our site

We now have a post, and maybe you also filled out your About section, and our blog is ready to be published. By default, all posts generated by Hugo will be drafts. Once you’re ready to publish a blog post, go ahead and remove that line in the post’s front matter (the metadata at the top). Hugo makes publishing incredibly simple with the following command:

$ hugo

And that’s it. The default publishing directory is public/ but this can be configured in the config.toml.

Hosting using Github Pages

Now comes the trickiest part of the whole process. Unfortunately, GH Pages does not support Hugo out of the box so it will take a little bit of configuring on our end. The Hugo documentation on publishing has useful information. Ultimately, it will depend on how you want your blog to appear online. I will highlight the three different ways that are outlined in the documentation.

1. Deploying via /docs folder

This is the simplest, but it comes with the downside that your repository must not have the naming scheme of <username>.github.io, and your site will appear as <username>.github.io/blogname/posts. I decided against this route as it felt “impure”.

2. Deploying via gh-pages branch

Once again, you cannot use the naming scheme of <username>.github.io if you decide to publish from a gh-pages branch. It will appear the same as if using the /docs naming scheme.

3. Deploying via master branch

This is the method I ultimately decided on as it allows for publishing the blog on <username>.github.io. However, you cannot push the entire repository as it won’t render the blog. In this case, the root directory of the repository must be the public/ folder. But what if you would also like to version control the source? This is where it will get a little messy and you must create two separate repositories to accomplish this. I ended up figuring it out on my own but after reading the rest of the documentation, the same process is also outlined here in better detail than I can do it justice.

Fin

Great. We’ve walked through all the steps of installing Hugo to publishing to Github Pages. Now we have a fully configured blog that allows us to publish on whim with two simple commands. The whole process was facilitated by Hugo’s excellent documentation. Now all that’s left is just messing around with the styling and getting it exactly to our liking. If you have any questions or comments let me know!