Set the ground work for the rest of the series by setting up a Hugo site and learning some of the conventions.
Familiarity with HTML/CSS, command line usage, some programming knowledge
Git (for installing themes and code-along repositories)
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
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.
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.
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:
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).
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:
Then, find your
config.toml and add this line:
If you want to use a different theme or install option, check out the great options at https://themes.gohugo.io/
layouts folder, add an
index.html page with something like this:
Now you can run the server (
hugo -D server) to see the content at localhost:1313:
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
contentfolder 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.
hugo new site <site name>
hugo -D server(
-Dmeans drafts will be visible)
hugo -D(with drafts)
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