In this article we are going to review all the main directories and files that we find in a Hugo project, to begin to know the framework in more detail.
Hugo is a very powerful static site generator. In past articles we have already been explaining how, in a practical way, to create a website. We also learned to install and .
With this information, you are ready to enjoy this fabulous tool, but surely there are many other things that you would like to know. So in this article we are going to take a bird’s eye view to see the main components that we have in a Hugo project.
Configuration config.toml
We start with the Hugo configuration file. It is written in a plain text code in a file located in the root of the project. It is initially called “config.toml” but could be written in other formats such as “config.yaml” or “config.json”. Each format has its own writing rules and syntax, but in the end they are just plain text files. It’s a good idea to stick with config.toml as most of the documentation is covered with this type of file, as well as code from other projects where we can learn things from.
We could even define several configuration files, with the “hugo –config” command as we see in the documentation, although at the moment I don’t see it as necessary. In addition, we could express the documentation in different files in a “config” folder, separating the configurations of each one of the issues to be touched in independent files. We are not going to go into details, we simply refer to the configuration documentation. https://gohugo.io/getting-started/configuration/
What’s interesting is starting to learn about some of the things that can be found in this configuration file.
initial settings
In a newly installed Hugo project we will find the following configurations:
baseURL: This is the URL where we will definitely publish the site. It is very important so that all the links then work correctly, as well as image paths and other things.
languageCode It is the language code that our page will have. Basic to compose the RSS of the page, but also very useful for multi-language pages.
title Is the title of our website.
There is a huge list of possible configurations for sites, such as “theme” to declare the theme we are using, “taxonomies” to indicate the taxonomies and many other things that we will see in due course.
contents folder
We can consider this folder as the heart of our website. In it we find the entire content structure of the site, with all the pages and collections that we may need to generate.
The content of the site is expressed through files in markdown format and each markdown file generated in this folder will correspond to a page on the final site.
We can generate content with the commands you already know from the Hugo CLI:
hugo new contact.md
This creates a contact page in the “content” folder, whose markdown file we can then edit to change its content.
In addition, the content can be organized by folders, to obtain what would be a collection of pages within a section of the site.
hugo new contact.mdSo we create a page inside the “blog” folder, so it would be like one of our blog posts.
Hugo’s content organization is very powerful and we can achieve any type of content hierarchy, as complex as necessary.
static folder
This is one of the most important folders when creating a site with Hugo. It is where we are going to place all the contents that do not need any kind of processing during the Hugo build process.
Anything put in the static folder will be put, as is, in the place produced during the build process. Here will go images, files to download from the site, Javascript, etc.
File paths in the static folder
The most important thing to understand about this folder is that there is a path mapping between the root of the website and its content. Therefore, if we put an image in this folder, like this:
static/my_image.png
Once the site is built you will find yourself on the route:
{website url}/my_image.png
Obviously, it will be convenient for us to order the contents of this folder and not place all the files in the root, so generally that image will be placed in a subfolder:
static/images/my_image.png
Therefore the final path of the file will be:
{website url}/images/my_image.png
Keep in mind that we can have several “static” folders in a Hugo project, something very useful for example for multi-language sites, so that we can have our custom files for each region. This would be configured within the Hugo configuration file, but if you need more information, we again refer you to the documentation.
layouts folder
The “layouts” folder is also very important for the development of sites with the Hugo framework. In this folder we will place all the markup to build the website, for each of its sections.
Basically, what we will have in layouts is a number of templates with the HTML of the site, in which we can also use many configuration variables of the site, and of the contents that we have in each markdown file. These templates can also be built by means of partial blocks, so that they call each other to compose the complete pages, so we can better maintain the code of the page and avoid repeating code.
In addition, within layouts we have the ability to overwrite the layouts of the theme that we have installed, so that we can customize any page and design in detail, even when we are using an already predefined theme.
You already know them, because we saw them in previous articles. As you can imagine there is much more to see and, in fact, this is the folder that requires more knowledge from Hugo to be able to fully master the generated sites.
themes folder
In a Hugo project we can use themes or templates already built by us or other developers, to save a lot of development time to get beautiful and practical designs. This is great for not having to worry too much about the design and focus directly on creating good content for the site.
We have already talked about this matter in the initial articles and, in fact, one of the first things we did with Hugo was to install a theme, as well as to carry out customization later on.
We have not commented that within the themes folder we could have several themes installed. The theme we are using is defined in the config.toml configuration file in the theme variable.
theme=”aether”
assets folder
In assets we place all the site files that require processing by Hugo during the build process. Basically here we will have Javascript and CSS files with preprocessor code that we need to compile before committing the site to production.
So far in this manual we haven’t touched on this folder, but it is extremely useful and necessary when you want to use things like Sass or need to generate bundles from your Javascript code. Fortunately, Hugo can do these things for you and very easily, thanks to the “pipes”, which we will see later.
archetypes folder
This folder is also very interesting, because it allows us to specify the default fields for each content type within Hugo.
By default, when we create content with the CLI and the command:
hugo new my_new_content.md
This file is born with a series of fields defined in the archetypes/default.md file. If we wanted to redefine the basic code of each new content that is generated, we could modify this file.
But it is also very useful because it allows us to define a new content model for each type of collection that we have on the site. Let’s say that houses are advertised on a real estate site, then we could define a content with a series of default fields for each house that is going to be built in the corresponding collection of houses.
Again, something very useful that we will see in detail when the time comes.
data folder
This folder contains information about data that you can consume within content pages. Each Hugo content has a list of variables that we can write within the markdown file itself, in what is known as “Front Matter”.
However, sometimes you have large data sets that don’t need to appear in the markdown file, that are common to multiple pages, or that would make them unwieldy. So we can use the data folder to put the information here.
conclusion
With this article you have been able to acquire a bird’s eye view of all the main components of a site developed with the Hugo framework. The main goal was to recognize all the files and folders created when generating a new site with Hugo, so you don’t get lost in the basic architecture of the project.
Later we will cover topics more related to each of these components to continue learning how to use the static site generator.
In the next article we will learn more about .
Facebook Comments
Disqus