[Learn Hugo] Project Structure

Last time we talked about the difference between static and dynamic websites, and created a Hello World project using the Hugo CLI. This post will cover the project's folder structure in more details.

Here is our hello-world project:

├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
│   └── index.html
├── resources
│   └── _gen
│       ├── assets
│       └── images
├── static
└── themes

First of all, you have probably noticed that running the hugo server command created resources folder. This is a special place where Hugo puts all the generated resources, such as images or styles. We will talk about it later in the section about the Hugo pipes. For now, just know that this folder is generated by Hugo, and a developer don't put anything in there themselves.

The rest of the directories and files are managed by the developer.

archetypes

To understand why the archetypes are important, we have to introduce the front matter. In the context of Markdown, the front matter is a metadata provided as key value pairs.

For example, look at the following document:

---
author: Shakespeare
book: Hamlet
---

To be, or not to be: that is the question.

The snippet wrapped between --- is the front matter. In our case the keys are author and book, and the values are Shakespeare and Hamlet. Note, the value can be more complex data structure, like list or object. The format we are using is yaml. Hugo also supports the front matter provided as json, toml, or org.

Why is that important? Most of the content we will work with will be represented as Markdown documents. Using the front matter, will give us an ability to define some qualities of a document that will tell Hugo how to prerender the content.

Let's look at the actual example. Hugo has a command for generating the content. We will use it to create our first post:

hugo new posts/this-is-my-first-post.md

Running it creates the Markdown document with the following content:

--------
title: "This Is My First Post"
date: 2020-09-24T09:20:46-07:00
draft: true
--------

If we look into archetypes/default.md, we can see where the generated front matter is coming from. Let's modify the file default archetypes file to look the following way:

--------
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
featured: false
--------

Now, create another post:

hugo new posts/this-is-my-second-post.md

The generated front matter is different this time, and corresponds to our default archetype:

--------
title: "This Is My Second Post"
date: 2020-09-24T09:27:20-07:00
draft: true
featured: false
--------

As the website starts growing, having a structured content becomes more prominent. We will probably want to create more archetypes in the future. There are also some more advanced use cases, like defining the disposition of the generated content.

For now, remember that this is a place where Hugo looks when generating a front matter for the new content.

config

In our case, it is a single config.toml file. For a bigger projects it can be a directory with separate configurations for development and production environments. The supported formats are json, yaml, and toml.

There are many directives that can be provided in the config file. We will learn more about the most important ones as we progress further with the series.

content

We already used this folder while talking about the archetypes. Generally, this is a place for the content. If you are writing a blog, your posts will go here. If you want to teach people how to code, your tutorials belong here as well.

One thing to note, Hugo can separate the content based on type. There are multiple ways to define the content's type.

For example, our posts at content/posts/this-is-my-first-post.md and content/posts/this-is-my-second-post.md are of the type posts. It is defined by the name of sub-directory they belong to.

The type can also be specified in the content front matter:

--------
title: "This Is My First Post"
date: 2020-09-24T09:20:46-07:00
draft: true
type: tutorial
--------

Now, this document is no longer of the post but of the tutorial type.

data

This folder contains various data that a developer might want to display on their website together with the content. It won't be used to generate a separate page, but can be pulled in the context of any other page. Similarly to the configuration files, Hugo supports the data in json, yaml, and toml formats.

layouts

This is the folder containing the website's HTML. It is a separate topic in itself, and we will cover it in great details in the coming posts.

static

The folder is meant to be used for the files that should be served as-is, without any processing. It can be CSS, JavaScript, or even some media files, like pictures.

themes

Hugo is famous for having rich themes ecosystem, and this folder exists for hosting all the themes used by the project. Many tutorials make developers to start learning by installing one of the existing themes. Although it might be a good approach if you want to get going fast, starting from scratch will make your life easier in a long run. Ultimately, a Hugo theme is very similar to a Hugo website. Understanding of how the layouts and templating work will help you to use and modify any theme.

That's it for this section! Next time we will cover the layouts, templating and start building an actual website. Ciao!