Using Hugo

This is one of the first web projects that I’ve worked on for myself. Most other stuff I’ve worked on is enterprise-level stuff: .NET commerce portals, Reporting sites on MEAN stack, and .NET Framework stuff that originally used those Website Forms.

For a blogging site, you don’t really need all that. At worst you’re getting hit by a bunch of people once, and then they can get your sweet cached pages. Most of the time, you’re not getting a lot of traffic, and you don’t need a whole framework to handle that.

Static Site Generators fill the niche. You don’t want to spend all day writing HTML (trust me). It simply takes too much time. And you don’t need a server 24/7 computing new views on content if you’re really just distributing articles.

I’m new to Hugo, and I haven’t used Gatsby, Jekyll, or any of the other popular tools. What really attracted me to Hugo was:

1. It’s super easy to install
2. The basics of using it are transparent
3. It had significant promise for cool tools (at least from the marketing)

Hugo is a really cool tool. There are a lot of ways to set yourself up to publish consistently. There’s a sizable community of people using the tool and contributing to themes, and integrations.

So, You Want to Build a Static Site

The “Getting Started” Documentation on the Hugo Website is pretty good! So check it out if you haven’t already.

Good read, so what’s the rest of this article about? Well Hugo kinda assumes you already have a development environment. So if you’ve never used a terminal, or built a website then… well it might be rough.

How I Develop on Windows: Powershell

Small secret, most of the devices I own run some variant of Windows. I’ll straight-up say that it’s sometimes great and sometimes terrible. Scott Hanselman might be a Windows Guru, but not me.

I’m pretty handy with a command line, and I work professionally with Windows. Like, people pay me to write code that works in and on Windows. I like Linux, because you really get to know the nuts and bolts of what’s happening. What this usually means is I try to make Windows work a little more like Linux when I can.

Anyway!

If you too are a Windows user, then you’ll need a shell. Go with Powershell, or if you’ve already picked a shell… then you are probably already good to go you can just skip to here.

I really can’t tell you how to get started, so here is another article from the source! Once you can run ls, mkdir, etc. then you are good to go.

Getting cool stuff into your environment: Chocolatey

I like Chocolatey because it adds some of that *-nixy flavor you get with brew from Mac, and apt in Linux. It handles a lot of the installation stuff I don’t like doing: “yes - yes - Install” in a pop up dialog.

I need SCSS, so usually I go for:

choco install hugo-extended -confirm

If you’re going to use an external SCSS processor, webpack, or anything else, then don’t bother.

choco install hugo -confirm

You don’t need Chocolatey, but I like it. If you don’t want more stuff, and another configuration to watch, then you can go with the binary installer.

You’re finally done getting things ready to work: you can run hugo in the terminal and you get a status message back. Now… well we actually make the site.

hugo new site yoursite

This will generate a brand new Hugo website, with a default config. If you want to see that site in action, run this to get the built-in local server to test it out (don’t use this in production).

hugo serve

Once you run that, you should be able to see the default site on localhost:1313. Open up your browser and check it out, it now exists!

So, now that you are all set up, let’s dive into the most important stuff to work on for setup.

The Config

This is probably the most important file in the project. It controls loading, menus, permalinks, categories. What you get out of the box:

baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"

I’ll give a little taste of the config file below:

baseURL = "https://www.yockyard.com/"
languageCode = "en-us"
title = "Yockyard"

[params]
    description = "This is totally Your blog"

[menu]
    [[menu.main]]
        name = "home"
        title = "Home"
        url = "/"
        weight = 1
    [[menu.main]]
        name = "post"
        title = "Blog"
        url = "/post"
        weight = 2
    [[menu.main]]
        name = "about"
        title = "About"
        url = "/about"
        weight = 3

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

[taxonomies]
	category = "categories"
	serires = "series"
	tag="tags"

So what do you think… eh, not too crazy right?

By the end of this I have a bit more to add to this config, but I’ll explain each part in detail. I’ve used the default .toml file, but Hugo affords the ability to work with several common configuration file formats, more info on that here if you’re interested!

That First Bit

My top-level configs work on things that are site-wide. This includes things like the base URL, the language you’re saying the site is in, and the title. A lot of these configurations are used in other parts on the site. I touch on how some of these properties are handled in the next article in the series Getting Started With Hugo Partials.

If you’ve forgotten what the config looks like:

baseURL = "https://www.yockyard.com/"
languageCode = "en-us"
title = "Yockyard"

This is the simplest part of the site. “baseUrl” is the “root” of the site. This is what configures Hugo to link everything up and… well it kinda makes everything work when you do deploy.

I’d recommend you change these things for your site to fit your needs.

Next part is the ‘Params’

[params]
    description = "Jon Yocky's Blog"

This bit makes a subsection – “params” – which only has the parameter “description.” In this case, it really only sets what this site’s name is. This is a more readable version of what we just configured. Again you’d want to modify this for your site, like “Blogzilla’s great place.”

Menus

[menu]
    [[menu.main]]
        name = "home"
        title = "Home"
        url = "/"
        weight = 1
    [[menu.main]]
        name = "post"
        title = "Blog"
        url = "/post"
        weight = 2
    [[menu.main]]
        name = "about"
        title = "About"
        url = "/about"
        weight = 3

This bit of code is one of the first bits of setup. The menu system in Hugo is pretty good, and these config settings are the backbone of setting up these menus. You don’t strictly need to set this up, but I’ve seen that I wanted to use this right out of the gate. The Hugo documentation is here and it covers most of the most important bits. For my system, these 3 categories are all I need. You can see them up top of the site!

Using these menu configurations for your site like this won’t work out of the box. Oh no, I’ve had to put in a bit more work to get the site doing what I want; but this is a start. And if you use one of the Hugo community’s highly recommended themes, then you’ll probably have to do way less work than I did to get a nice looking menu!

Breaking this down, each menu section can use a subsection. I’ve only used one, so I’m using each as the “main” menu. For me, I’ve not needed to use the multiple menus features, but I can see this being useful in the future. Say I break my blog down into things like “Jazz, RPG’s, Development” and uhhh I don’t know, “Rock Photography,” then you might see dropdown menus that utilize those sections. For now, every bit is its own section.

The Last Bits

These sections are a few organizational helpers:

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

[taxonomies]
	category = "categories"
	serires = "series"
	tag = "tags"

So, first is the permalinks for posts. This is built off each post’s attributes (which are built by Hugo automatically). I like this setup, because it keeps everything organized by the typical ISO-style year-month-date organization. What usually happens with the Hugo system is it takes the title from the article markdown (we’ll get to that in a blog post about blog posts) and makes that the link to the post based off that. Later on, if you want to make another “getting started with foobar” post then you’ll need some other permalink system, otherwise your titles might do something unpredictable. And I don’t like that.

The taxonomies configuration in Hugo is a whole new type of super grouping. Check out the Hugo documentation here for more info on it, but I’ve used the semi-standard groupings from the documentation I linked.

The “series” grouping is something I’m utilizing for this series. It basically lets you make groupings for articles. If you had a series of, say, 3 articles about your favorite jazz artist, then you could group those together, then carve out a separate part of the site dedicated to that particular savant.

I haven’t quite implemented the use of series yet, but once this series is a series then I’ll add that article to the series. And maybe I’ll stop saying “series” so much.

Update
I actually completed the series feature before publishing this article, so now you can see how I’ve got that set up.

Let’s Wrap This Up

I’ve expounded on this enough-in short, Hugo is pretty flexible. It’s got a lot of features I really like, and you can use it for a lot of different things. For me and my blog, I think it’ll do quite well.

If you’ve followed this post and not set up anything else, you don’t have a website yet! Right now you will have the skeleton of a website. If you run

hugo serve -D

Then you’ll see this on localhost:1313 (by default), and you’ll get a blank page. You can make new posts and try things out, but you’ll need a text editor… just look up “Visual Studio Code” if you’re still in the late 2010s. Oh boy, text editors is another article for later.

If you want your non-site to display something, check out this repo: it’s an MIT-licensed template that I’ll be using in the next article when I talk about the templating system. I’ve updated that repository with my changes to the config, so it out here. The changes I made will be in the /01 folder.

My future articles will dive into working with content and HTML templates, making the site actually look presentable, and how I worked with the Material CSS.