Build and deploy websites with HUGO

HUGO is basically a free open-source static site generator, which means you write the code and compile it into an optimized website¹HUGO. The world’s fastest framework for building websites..

There are many other static site generators out there such as Gatsby.js, Jekyll, Nuxt, and they all focus on dynamic content and speed optimization. For this occasion, we’re be talking about HUGO.

📍 How does a site with HUGO look like?

Sites made with HUGO doesn’t actually have to look the same. HUGO has themes you can use and customize but you can also code your own. But for a more explicit answer, here are two quite different examples of sites using HUGO

Traditional layout

Out of the box layout

📍 Install HUGO

As it is shown on the documentation, install HUGO is incredibly fast, and it doesn’t matter which OS you’re using, it’ll work⁴HUGO. Quick Start..

brew install hugo

brew install hugo

choco install hugo -confirm

📍 Create a new project

First of all, I personally recommend creating a blank GitHub repo – we’ll use it later on the deployment – and on that route run the following command on a terminal:

hugo new site hugo-example

In this case, hugo-example is the name of our site. After running this command the project will look like this:

All the folders except archetypes are empty, and every one of them as a specific purpose.

• 📁 archetypes: an archetype is a template used when creating new content⁵HUGO. Archetypes., in other words, an archetype is a file that goes on the archetypes folder that defines the front matter – content and/or metadata – of the post/page. For instance, the default.md file adds title, date, and draft as front matter (in this case is both: content and metadata) for our posts and pages.

• 📁 content: HUGO supports nesting at any level⁶HUGO. Content Organization., this particular folder is for the content itself. Usually, we have posts and pages subfolders for a better organization but it is possible to create as many subfolders as you need.

• 📁 data: This folder is for configuration files in JSON, YAML or TOML format⁷HUGO. Directory Structure..

• 📁 layouts: Templates in HTML format for views⁸HUGO. Directory Structure..

• 📁 static: Every static resource goes here, this includes javascript, images, CSS. Here you can also create subfolders for better organization⁹HUGO. Directory Structure..

• 📁 themes: Here you’re going to have as many themes as you want

• ⚙️ config.toml: In this file, you set up the global configuration of the project such as language and theme used.

📍 Add a theme

HUGO’s official site has a huge library of themes for you to implement to speed things up & customize as your needs. You can check the whole library here. For this example, we’ll use Hugo Cards.

To download the theme it is possible to clone the GitHub repo or just download it and move it to the themes folder.

git submodule add url-of-the-theme themes/theme-name

In our case, this will be the correct URL:

git submodule add https://github.com/bul-ikana/hugo-cards.git themes/hugo-cards

The project will look like this

As you can see, the theme itself is another project with the same structure as the original one, but with its own content.

📍 Apply the theme

After adding the theme to the project it is necessary to apply it using the config.toml file. Add this line at the end of the file and that will be it.

theme = "hugo-cards"

Remember that hugo-cards is the folder of the theme. This will be our config.toml file:

baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "hugo-cards"

The baseURL is the root of the site, for now, we don’t have a URL to change and it doesn’t matter – because we’re in local – but we’ll get to that point. For now, we can save our config file.

📍 Run the server

At this point we can run the server and see how our site looks, to do that let’s run this command on the terminal:

 hugo server -D

Right now we have our functional site with a theme but with no content, as a result, we have this:

📍 Add content

To add content we can do it manually or use the HUGO command. If you use the HUGO command make sure to use a different terminal window than the one running the server.

hugo new type/name.format

hugo new posts/hello-world.md

This will create the hello-world.md file on the posts folder inside the content’s folder.

This is the content of our new post:

---
title:"Hello World"
date:2019-12-14T14:39:52-06:00
draft:true

---

Thanks to the hugo-cards theme we know we can add images, for that let’s create the images folder on the static directory. After that, we have to specify which image our post will use on the front matter.

And to specify that in the post we need to add the attribute img

---
title: "What is Bootstrap"
date: 2019-12-14T14:39:52-06:00
draft: false
img: bootstrap.png

---

⚠️ Note: the name and the format must be the same as the image on the static folder.

After that, we can add our content and save it. After saving it the server will automatically reload the page.

Result of the site

Single post page

📍 Compile the project

When the project is done, you can run the command to compile it.

hugo -D

📍 Deploy with netlify

netlify is a service we can use to deploy our HUGO site. After login into the platform, we can go and click the New site from Git button.

On the next page, we select the Git provider, therefore for this example we select GitHub.

When you select your provider you are going to give access permissions to netlify and then, select the repo of your site.

Default settings are fine to deploy so you can click on Deploy site. And that’s it, your site is alive for free.

📍 Final details

After your first deployment, you can click on “site settings” and change your site’s domain. When you change it and your site is online, you need to change the config.toml file with the new domain.

With that being said, our config.toml should have this line instead of the placeholder it used to have.

baseURL = "https://hugo-example.netlify.com/"

⚠️ Note: If your deployment fails it might be because netlify could be using a different version of HUGO, to fix it you can add this netlify.toml file on the root of your project.

---

📍 Check out the result

📍 Repo of the example