Getting Started with Hugo

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
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:

Terminal

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:

Hugo directory

As you can see, with all folders expanded, there is almost nothing in the project. Let’s fix that.

2. 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. Front matter is a way to set metadata for a page but more on this later.
config.toml: default configuration for your project goes here. YAML and JSON are also supported if you prefer.
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.
static: contains all your assets that don’t need processing. Hugo will simply copy any files here to your built site without touching them.
themes: any themes you’re using can be added here.

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. 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