Hugo Journey and Setup Guide

I have a habit of spending a good bit of time researching things before I take action. Whether it be making a purchase, deciding where to go on vacation, or even what to eat for dinner. Finding a blog engine was no exception.

Of course you have Wordpress - but I’ve tried it over the years helping people out and I’m not a fan. Then there was Jekyll - I’m not too familiar with Ruby. I took a look at Ghost - but I got frustrated with existing themes and didn’t feel like digging in to make my own. Finally I landed on Hugo - simple markdown, config driven, and a template engine that felt familiar.

Now as of writing this article, I haven’t customized the layout much past the basic theme I found aside from a few small customizations. But I feel a lot more comfortable with the beginning product, I know it can evolve, it’s familiar enough that I can be comfortable with it, but unfamiliar enough that it can challenge me with a few things here and there.

Here’s a quick guide on how to get things up and running locally pretty quickly. As always with these articles, please give me feedback as I know I don’t always do things the best way, and that’s how we learn 😊

Prerequisites

First and foremost, I’m on a Windows 11 machine. I don’t mind Windows, but I feel pretty comfortable in a linux environment. WSL has evolved a lot over the years, and I thought I’d use it for development purposes on this machine. VS Code is my go to IDE for the majority of my development work and integrates seamlessly with WSL for the work I’ve done so far with it. If you have a different OS or different setup, things will be slightly different, but you should be able to follow along and replicate pretty easily.

The documentation for Hugo was really easy to follow and can be found here: Hugo Quick Start

1. Windows 11
2. WSL (I’m using Ubuntu 24.04) Install WSL on Windows
3. Visual Studio Code

Install Hugo Dependencies

First things first - in order to install Hugo, we need to install both Git and Go. Hugo’s installation documentation does state that Dart Sass “is required to transpile Sass to CSS when using the latest features of the Sass language.” Fortunately, since we will use Snap to install Hugo, the Snap Hugo package already includes Dart Sass!

Git

After running your usual:

sudo apt update

Run:

sudo apt install git

You’ll probably want to go ahead and configure your name and email for committing changes in the future, so run the following commands:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Go

Official Go install directions for reference: Go Download and Install

Next we will install Go. Here’s how I did it inside of WSL. This may be different for you if there is a new version of Go available.

wget https://go.dev/dl/go1.24.3.linux-amd64.tar.gz
rm -rf /usr/local/go && tar -C /usr/local -xzf go1.24.3.linux-amd64.tar.gz

I had to manually add /usr/local/go/bin to the PATH environment variable. I have Zsh as my shell, so I had to add the following lines to my ~/.zshrc. A similar approach can be used if you are using a different shell, such as the ~/.bashrc for the bash shell.

...
export PATH="$PATH:/usr/local/go/bin"

Then apply the changes:

source ~/.zshrc

You can verify by typing the following in your shell to make sure it worked:

go version

If you got output similar to

go version go1.24.3 linux/amd64

Congrats! You’ve got your dependencies installed!

Installing Hugo

Now that we have our dependencies installed, let’s install Hugo through the Snap package manager. I installed Hugo through Snap because Hugo’s installation instructions do state that the Hugo version available in package repos may in some cases not be the latest version. Hugo’s documentation also has instruction to install Hugo via Homebrew should you choose that direction.

To install Hugo through Snap, run the following command:

sudo snap install hugo

And just like that, we’re almost ready! One thing tripped me up - possibly because I’m using Zsh - but it might apply to other shells. You see, the bin folder for applications installed via Snap is not in my PATH environment variable. Just like we did after the Go installation, let’s add the executable’s parent directory to our ~/.zshrc file, ~/.bashrc file, or analogous file for other distributions.

...
export PATH="$PATH:/snap/bin"

Then apply the changes:

source ~/.zshrc

And voila! You can verify Hugo is installed by running the following command:

hugo version

And the output should be something similar to

hugo v0.147.8-10da2bd765d227761641f94d713d094e88b920ae+extended linux/amd64 BuildDate=2025-06-07T12:59:52Z VendorInfo=snap:0.147.8

Tell the World!

One thing I’ve always found awesome about development and the web is that your work is instantly available for the entire world to see. There aren’t many mediums in which that can happen. I don’t take it for granted, and always think about that before pushing something out because I know it can affect a lot of people. Not necessarily my blog, well maybe one day, but other products I’ve worked on.

With Hugo, it doesn’t have to be a blog. The templating engine is pretty powerful and at the end of the day, it generates HTML like everything else. Hugo just gives you a different experience to build your website compared to writing strict HTML, other static site generators, server side rendering frameworks, or fancy javascript frameworks. Don’t overcomplicate creating a simple site. But if you really wanted to, go ahead and throw React, Angular, Vue, or anything else in there. It’s all up to you.

So with that, let’s build a site so you can showcase your ideas to the world. I won’t walk you through everything, as I think the Hugo Documentation is fantastic. However, I’ll reiterate their instructions to stand up a quick site, select a theme to use, and create your first post.

Generate a New Site

First, navigate to your parent directory where you want the Hugo project to live. Run the following command to generate the project template for a new site:

hugo new site my-website

Change to the project’s directory:

cd my-website

Finally, let’s go ahead and set up source control so we can keep track of changes and use the submodule feature for themes.

git init

Choose Your Theme

Now we want to pick a theme to use. You can definitely create your own theme if you are up for it, however I’ll follow Hugo’s lead in their documentation with the Ananke theme. There are also a ton of other options you can find here. I ended up going with the DoIt theme as a starting point. Yes, my site looks almost identical to it at the time of this article, but at this point this site is an MVP and we’ll customize it more soon 😃

There are a couple ways to implement a theme, but I prefer the git submodule route. Run the following command to clone the Ananke theme as a submodule inside of your project’s root folder:

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

Now we want to tell our project’s configuration to use the theme. You can do this a few ways, but just to get your eyes on the config file you can open the hugo.toml file in the project’s root directory and add the following line to the end of the file:

...
theme = 'ananke'

Now run the following command to start up your Hugo development server

hugo server

The console will output the localhost URL including the port number to view your site. Congrats, you are up and running!

Create Your First Post

Yes, it looks a little bland. There are a lot of configuration options including menus, images, posts, search, and more for you to play around with and customize your site. But we need to add content in there first. To create your first post, stop the server and run the following command:

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

Open up your new file and you’ll see what is called front matter. This is pretty much metadata that gives information to the templating engine and site build engine. It should look similar to this:

+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
draft = true
+++

Below the end of the front matter (below the closing +++ line), and add some content with markdown! You can learn all about markdown here. It is a standardized way to take notes and build documents, which in this case get translated to websites.

The first content I wrote was the obligatory Hello world, and my file contents looked like this:

+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
draft = true
+++

## Hello world

After you add your own content, let’s rerun the hugo server command with a couple flags. The -D flag tells Hugo to include drafts, which is defined in the front matter for each content. The --disableFastRender flag enables full re-renders on changes, which is helpful as you are building out your site and making changes.

hugo server -D --disableFastRender

And there you go! It is still pretty bland, yes, however you know have a website with your first bit of content that the world can see!

Next Steps

I don’t want to just leave you hanging there. To start customizing your site, it would be good to start with the Hugo documentation so you have a good idea of how things work and where to find what you’re looking for.

The next place to go is your theme’s documentation. Here is a link to the Ananke git repo where you can find helpful documentation such as setting up a hero image, adding comments, and more.

I will add another post in the future documenting how I got this site up and running on Cloudflare Pages (here’s a hint, I followed Cloudflare’s Documentation) 😉

Let me know in the comments if this was helpful and please link your site that you’ve built!