Building Your First Hugo Website

Published: 2021 July 19

Last edited: 2022 May 04

software development web development static site generator Hugo technical guide

Who this is for

If you want to build your first website with Hugo, this article is meant to get you started.

It is not an exhaustive or extensive guide. There are other good resources for that, and several are linked below.

But here you’ll find instructions on the critical path to get a website up and working.

There’s magic in motion, and just getting started is often the most important thing.

So, let’s get started.

Build your first Hugo website

Install Hugo

Install Hugo on Linux

Follow the instuctions from Install Hugo on Ubuntu 20.04 or Ubuntu-based distributions by Vishnu Damwala:

Open your terminal (Ctrl+Alt+T) and run the below command with sudo privileges
sudo apt update && sudo apt install hugo

Install Hugo on Windows

Follow the instruction from Installing Hugo on Windows | Hugo - Static Site Generator | Tutorial 2 by Mike Dane

Install Hugo on Mac

Follow the instuctions from the Official Hugo Quick Start Guide:

Homebrew and MacPorts, package managers for macOS, can be installed from brew.sh or macports.org respectively.
brew install hugo
# or
port install hugo

Or follow the instructions from Installing Hugo on Mac | Hugo - Static Site Generator | Tutorial 3 by Mike Dane

More installation options

If none of the above work for you, you can find more details and options at The Official Getting Started - Fundamentals - Install Hugo Guide.

Confirm Hugo is installed

Open a terminal and type the command:

hugo version

You should see a message indicating the version number.

Create your first site

In the terminal, navigate to the folder where you want Hugo website files to reside.

Then enter the command:

hugo new site my-first-hugo-website

You may replace my-first-hugo-website with another name, if you prefer.

You should see a message beginning with

Congratulations! Your new Hugo site is created in…

Open your preferred development environment or file explorer to the folder you selected to see the newly-created files and folders for your website.

Select and import a theme

We’ll make use of the Minimal theme and it’s included exampleSite in order to build a working website that we can alter.

Select a theme

Go to themes.gohugo.io to see examples of the many themes available for Hugo.

For this tutorial you’ll use the Minimal theme.

To download the Minimal theme, go to it’s repository on GitHub. Click the Code button and select Download ZIP.

Save the ZIP file locally.

Import a theme

Extract the files from the ZIP archive.

Rename the extracted folder from minimal-master to minimal. (NOTE: GitHub appends -master to files saved in this way. You will need to rename all themes you download to remove that additional text.)

Copy the renamed minimal folder into your /my-first-hugo-website/themes/ folder.

Copy the exampleSite config file

Navigate to the /my-first-hugo-website/themes/minimal/exampleSite/ folder.

Copy the config.toml file. (NOTE: For some themes this will be a config.yaml file.)

Paste the copied config.toml file into the /my-first-hugo-website/ folder, overwriting the existing file. (NOTE: If you copied a .yaml file from your theme, be sure to delete the config.toml file since it won’t be overwritten in that case.)

Copy the exampleSite content

Navigate to the /my-first-hugo-website/themes/minimal/exampleSite/content/ folder.

Copy everything inside the folder. This should be a /post/ folder, a /project/ folder, and an about.md file.

Paste the copied files and folders into the /my-first-hugo-website/content/ folder.

Start the Hugo server to see your website

In the terminal type the command:

hugo server -D

Open a web browser to http://localhost:1313/ to see your new site.

You can leave the server running to see changes applied as you make them. Later, once you are finished, you can press CTRL + C to stop the server.

Create your first post

Since we kept the server running so that we could observe our changes you’ll need to open another terminal and navigate to the project folder: /my-first-hugo-website/.

In the terminal type the command:

hugo new /post/my-first-page.md

You may replace my-first-page.md with another filename, if you prefer.

Look at your web browser and editor to see the new blank page that was created.

Experiment to make it your own

You now have a working website, but it’s filled with someone else’s content.

It’s time to start changing things to make the website your own.

You can do that through experimentation - iteratively testing and tweaking things as you go - or by following more advanced guides to learn how Hugo works.

I recommend Mike Dane’s Hugo - Static Site Generator | Tutorial as a great next step to learn the basic elements that make up a Hugo site.

Build your website

Once you have altered the site to your satisfaction, it’s time to output the website files.

In the terminal, enter the command:

hugo

The generated files will be output to the /my-first-hugo-website/public/ folder.

These files can then be copied and uploaded for web hosting.

Thanks

A thanks section is always incomplete. Nevertheless we specifically want to express appreciaton to a few people.

Thanks to Mike Dane and his Hugo - Static Site Generator | Tutorial for making Hugo approachable and understandable for beginners.

Thanks to the Hugo Project and Hugo Contributors for creating and maintaining the project.

Additional resources

Overal guides

The Hugo - Static Site Generator | Tutorial by Mike Dane is a great resource for getting up to speed using Hugo. He starts at the very beginning and works methodically through the basics of using Hugo.

Official Hugo Quick Start Guide

Official Hugo Documentation