A Step by Step Guide to Building Your First Hugo Site

Nowadays, having a website is as essential as having a phone number for your business. A website can be used to showcase your products in your business or your work with images and videos. On the other hand, creating a user-friendly and secure website is not as easy as you might think. When the database and assets grow, your website will be slow. Also, you will have to keep the site up to date to keep your site safe from online attacks. This is where Hugo comes to the rescue. In this beginner-friendly tutorial, we will guide you through the process of setting up a brand-new Hugo site from scratch. By following this step-by-step tutorial, you will be able to learn how to install Hugo, create a new site, use themes and write content. At the end, we will guide you on how to deploy your Hugo site to the web. So let’s get started.

What is Hugo?

Hugo is an amazing fast and highly customizable static site generator. Among hundreds of features, it has all the tools like images and assets optimizations, SEO, search, categories, tags, widgets and almost everything that you can expect from a CMS (Content Management System) like WordPress. But the main difference in Hugo is, that Hugo usually does not need a DBMS (Database Management System) like MySQL, PostgreSQL or any other. Instead, it depends on static files. Yes, we can store our content in something called Markdown files. At the top of these Markdown files we mention the title, description, categories and tags of the post and we call this section “Front Matter”. You can read more about Front Matter from their official documentation page.

Install Hugo

As explained earlier, Hugo is a static site generator. So, first, we need to install it on your computer. Fortunately, Hugo supports all the major operating systems like Linux, Windows and macOS.

Linux (Debian/Ubuntu)

Install Hugo with apt-get in Debian-based distributions.

sudo apt-get update
sudo apt-get install hugo

Windows

Use Chocolatey to install Hugo by entering

choco install hugo -confirm

macOS

Open your Terminal and use Homebrew to install Hugo on your macOS.

brew install hugo

Alright, now you can run hugo version command in your terminal window to check whether the installation is successful. This command should display the installed version of Hugo. At the moment writing this tutorial, the latest Hugo version is v0.124.1. However, due to the delay of system package releases you could get a little bit older version and it should be just fine.

Create a New Hugo Site

Since we have already installed Hugo on our computers, the very next thing that we need to do is create a new Hugo site. For that,

1. Open a Terminal or Command Prompt window.

2. Navigate to the directory where you need to store your site files.

3. Run the following command:

   hugo new site hello-world-site
   

Replace hello-world-site with your site name. This command will create a new directory with the basic file structure of a Hugo site.

Add a Hugo Theme

Themes are responsible for the appearance and user experience of your Hugo site. Hugo offers a wide range of ready-to-use themes. You can simply browse themes.gohugo.io and select a theme which fits with your preferences. In addition to themes.gohugo.io theme gallery, you might be able to find Hugo themes in Github as well. Otherwise, of course, if you cannot find the exact theme you need, you can even create your own theme.

Usually, you can get the related information that you need to install a theme in their read me files or documentation. Look for something like below which gives the necessary instructions to add the Hugo Git theme repository to your Hugo site’s themes directory.

git submodule add https://github.com/username/theme-name.git themes/theme-name

or

git clone https://github.com/username/theme-name.git themes/theme-name

What they do is simply add (submodule/clone) a theme into your Hugo site’s themes directory. For this tutorial, lets use the Hugo Blog Awesome theme.

cd hello-world-site
git init
git clone https://github.com/hugo-sid/hugo-blog-awesome.git themes/hugo-blog-awesome

Now we can activate the added theme by mentioning its name in your site’s hugo.toml file like below.

theme = "hugo-blog-awesome"

Create Content

At this moment, we do not have any content on our site. So we can add new posts.

Add a new post

hugo new posts/my-first-post.md

This command should create a Markdown file called my-first-post.md in content/posts directory, where you can write your post. Open the newly created my-first-post.md in a text editor. Initially, it should look like below.

+++
title = 'My First Post'
date = 2024-04-01T10:57:35Z
draft = true
+++

You can change the title, date, draft status and even tags and categories in this front matter section. After that, you can add your content.

Running the Site Locally

Now it is time for a preview of our newly created Hugo site. For that, simply run the below command.

hugo server

Once the site build process is finished, visit http://localhost:1313 in your web browser to see your site in action.

Now you do not need to refresh the page when you change something in the site. Hugo will detect file system changes and automatically refresh the site as you make changes.

Deploying Your Site

Create posts and make changes as much as you need. When you are satisfied with your site, you can build it for production deployment or hosting.

For that, run the following command. This command will generate the static files of your site in the public directory.

hugo

Once it has finished the production build, you can simply upload all the contents of the public directory to your hosting platform.

Conclusion

Congratulations! You have successfully created and built your production-ready Hugo site. This tutorial covered the essentials of Hugo static site generator. Hugo’s speed, flexibility and ease of use make it an excellent choice for web development projects. No matter whether you are building a personal blog, a portfolio or a corporate website, Hugo offers all the features to bring your digital presence to life. Continue experimenting with different themes and customizing your site to truly make it your own. Happy building!