Getting Started with Hugo

Farrel Burns, Developer Evangelist

Duration: 2 hours

Expertise level: Beginner

On this page:

Prerequisites:

Hugo installed
Familiarity with HTML/CSS, command line usage, some programming knowledge
Git (for installing themes and code-along repositories)

What you’ll learn here

Creating a new Hugo project
How to use a Hugo theme
Understanding how Hugo is structured
More Hugo conventions for your project
Basic Hugo command line options

What is Hugo, and why is it good?

Hugo is an extremely fast, conventions-based static site generator (SSG) framework. What sets it apart from other SSGs is its use of the Go language for processing, giving it unparalleled speed compared to other options.

Also, because it’s heavily conventions-based, you’ll often need to follow strict design patterns to use the framework properly. One particular example is Hugo’s strict separation of layouts and content. Adding HTML pages, writing all your content in them, and directly linking to them simply won’t work in Hugo. Although this requires you to do some initial learning, it ensures you are sticking to consistent design patterns.

Let’s get started!

This first Hugo tutorial should give you a feel for how things work before diving in deeper. Let’s understand the foundations by creating a project and looking at typical Hugo structure.

1. Create a project

If you’ve got Hugo installed (installation docs here if not), let’s first start a basic project and dive in:

In your preferred terminal, navigate to where you want to be and create a project. Feel free to use this command and modify it as needed:

Shell

cd desktop && hugo new site my-hugo-site

If you accidentally blinked, you probably missed Hugo in action. It’s not an error - it really is that fast!

Now, open your Hugo project in your favorite code editor (such as VS Code) and inspect the contents:

As you can see, with all folders expanded, there is almost nothing in the project. If you run hugo -D server now, you’ll also see nothing at localhost:1313 (Hugo’s default port).

2. Install a theme

Let’s learn the basics of installing a theme here to make life easier. In the rest of the lessons, we won’t use a theme, as we want to learn the magic of Hugo and understand it properly.

In your terminal, from the base of the project, clone the Git repository git clone or wget (if you have it installed) to install a theme:

Shell

git clone https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

Then, find your config.toml and add this line:

config.toml

theme = "ananke"

theme = "ananke"

Note

If you want to use a different theme or install option, check out the great options at https://themes.gohugo.io/

3. Add some basic content

Inside the layouts folder, add an index.html page with something like this:

index.html

<!DOCTYPE html>
<html lang="en">
	<head>
		<title>Hugo | Home</title>
	</head>
	<body>
		<h1>Welcome to Hugo!</h1>
		<p>Hugo is the world’s fastest framework for building websites!</p>
	</body>
</html>

Now you can run the server (hugo -D server) to see the content at localhost:1313:

Hugo structure overview

Here’s a short reference for the purpose of each folder/file in Hugo’s structure.

archetypes: this is where you create default front matter for content. This can be handy for organizing your default needs, but purely optional.
assets (not a default folder): anything that requires processing by Hugo Pipes (such as SCSS or images) lives here.
content: all your content (generally Markdown) for pages lives here.
data: supplemental data files live, acting as a surrogate “database”.
layouts: all page templates for your content folder live here. There are some strict conventions to get your head around, but we’ll get to that later.
public: your generated site will be created here, which you can deploy online.
resources: a folder where Hugo puts assets for caching. Not really useful for you as a user.
site: this folder appears when you build your site. It is the output folder for your finished site, which you can put online.
static: this is the counterpart to assets, except that anything that you don’t need to be processed goes here. Hugo will simply copy any files here without touching them.
themes: any themes you’re using should be added here.
config.toml: default configuration for your project goes here. YAML and JSON are also supported if you prefer.

Command line basics

Create new project: hugo new site <site name>
Start a development server to view your site: hugo -D server (-D means drafts will be visible)
Generate your static site for production: simple hugo orhugo -D (with drafts)

What’s next?

This is a lot of information to consume in one sitting, so in the next lessons we’ll put it into practice. Feel free to play around with this basic project, but in the next lesson we will deal with a pre-built example project with the building blocks of Hugo pages

Installing Hugo

Layouts in Hugo