How to Build Sites With HUGO Part 1

Dec 17, 2020 10 mins read

Web

Motivation

When you want to deep into the adventure of creating your webpage, for any reason, starting a new project, or just maybe professionally upload your CV. You can be overwhelmed by all the possibilities (mostly paid) that you can use.

These alternatives can go from the most “basic” and automatic providers like Wix passing for the most common contents managers systems (CMS) such as WordPress, Joomla, and many others. Or maybe you want to draw your HTML and CSS to achieve this task in a more sophisticated way.

I have to admit that I have desisted the idea of having my personal web page for many years, saying the same phrases, it is too expensive to pay for web hosting, just to have a WordPress or any content manager. Been constantly frustrated about that idea, I have found a cheap way to host for free on different systems, yes, for free!

Now we are talking, but designing a static webpage seems to be rigid, old fashion and maybe tedious. Because, In my case after a few weeks of working on a single HTML to upload my CV, I was suddenly presented with the following question: and If I need to modify or add something? And if I wanna have a space to share ideas. After that, I have found this idea of ‘static content managers’, the idea behind that is you only take care of the content in markdown files (.md), and the “framework” will generate the HTML for you. Since I now have a good option (free) for hosting my web page I have expended some time investigating this idea and I have found HUGO and I wanna share it with you as my very first post on my webpage.

HUGO is a static content generator written in Go, in its webpage it is claimed as the world’s fastest framework for building websites. As a professional Go developer, I do know the advantages of this language and the performance of the final binary using that language. So, after reading the great documentation on the page I can say that jump into the static generator is fast as they claim. Also, it can be as customizable as this site has resulted. I am far from an expert in front-end development, all my daily work is in backend development and firmware development. Nevertheless, I am feeling very happy about the result. Well after trying to sell you the idea about this tool, let me guide you about the steps that I followed to have this site up and running.

Installing HUGO

As I have mentioned before HUGO was written in Go, by default you will get all the go-libraries statically linked in the final binary. This is handy, because the installation is as easy as just download a build form the releases page and add it to your PATH. I encourage you to visit the documentation about this topic and follow the specific instruction for your operative system documentation.

After a successful installation, you can go over a command line and try to run the following command to see your version, please notice that I have build my own version so the build version comes from the DEV branch.

$ `hugo` version
Hugo Static Site Generator v0.80.0-DEV linux/amd64 BuildDate: unknown

Create your first webpage

After the installation of the hugo command you can start the development of your website. Hugo provides a way to start a new project using the following command hugo new site mywebsite. Where you can specify your website name in this case ‘mywebsite’. After that you will be prompted with a message similar to the shown below. As you can see this prompt is telling you the next steps in the development process, first you will need to choose a theme form https://themes.gohugo.io/. With this step your are reusing someone’s code to give a shape of you website, this is helpful you don’t wanna deal with the HTML or CSS in your web site.

$ `hugo` new site mywebsite
Congratulations! Your new Hugo site is created in /tmp/mywebsite.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.go`hugo`.io/ or
   create your own with the "`hugo` new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "`hugo` new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "`hugo` server".

Visit https://go`hugo`.io/ for quickstart guide and full documentation.

Understanding the folder structure

Before going any further, let’s examine the content’s of the directory

$ ls
archetypes  config.toml  content  data  layouts  static  themes

archetypes: This folder defines the behavior of hugo new command. This is useful when you start to add additional meta-data to your md files.
config.toml: This is the configuration file for the hugo project.
content: This is the folder where you will store the real content of your site, the md files. Inside this folder you can create any desired sub-structure to keep all sorted as you want.
data: In this folder, you can store data files such as json, toml or yaml. This can act as a static data store.
layouts: Here you can place your own custom html files in the case that you want to create your custom index.html or maybe any about information page. For example in the case of this web-page, the landing page for josnelihurt.me is custom. Personally, I have found this feature useful and flexible.
static: This folder will hold all the static resources for your web-site, such as style-sheets, javascript files, or images to be served in your web-site.
themes: This folder will live all the themes that you download or create.

The same structure is replicated under the folder themes, in other words, your site will be extending the basic functionality for the theme. If you wanna deep into the documentation, this is the link for the corresponding section.

Downloading a template

Now you can download a simple template to continue with the process, I will use erblog for this example but there a bunch of them in the themes page. I will use the git clone command to download the theme into the theme folder. But you can download the zip file and extract it into the themes folder.

$ cd mywebsite
$ cd themes
$ git clone https://github.com/ertuil/erblog.git
Cloning into 'erblog'...
remote: Enumerating objects: 146, done.
remote: Counting objects: 100% (146/146), done.
remote: Compressing objects: 100% (106/106), done.
remote: Total 1483 (delta 81), reused 94 (delta 39), pack-reused 1337
Receiving objects: 100% (1483/1483), 24.22 MiB | 3.49 MiB/s, done.
Resolving deltas: 100% (707/707), done.
$ ls
erblog

After having download the theme you will need to configure your project to use the new theme. So in the config.toml file add the following line.

theme = "erblog"

This will set the theme in the project, and you can set any theme correspondingly. Every theme will have its special characteristics, this is due to the flexibility provided by hugo. But in general terms, hugo defines two main types of pages.

List Pages

The list pages allow listing the content inside the content folder, and for each content document that you add hugo will create the corresponding links to navigate through them. Additionally, hugo defines the concept of templates to modify the way that each type of page will be displayed. Usually, this work is done at the template layer, so if you don’t want to deal with it take your time choosing a good template.

Content Pages

The content pages will show the actual content of your page, for example, if you are creating a blog, this will be your blog entry. Like in the case of this page this is a content page, produced from the corresponding md called how-to-build-sites-with-HUGO.md

If you want to continue reading about this topic this link will provide the information, but again just in case you need to create your custom template.

Adding content to your webpage

Every template can organize the content as it was desired by the developer, for that reason I encourage you to take your time to read the features of the theme that you want to select.

In this case, erblog expects the blogs entries into the folder content/blog. To create a new entry using the following command hugo new

$ `hugo` new posts/hello-web.md
/tmp/mywebsite/content/hello-web.md created

$ cat /tmp/mywebsite/content/blog/hello-web.md
---
title: "Hello Web"
date: 2021-01-07T14:51:35-05:00
draft: true
---

Notice that a new file hello-web.md was created under the folder content inside the location of your hugo project. The content of the file is shown using the command cat and from that, you can see that some automatic data has been added, this section between --- is called the metadata for the file. The metadata allows to set some specials variables as you required, in this example it results only with title, date, and draft. Those variables can be configured to be created using the files into the folder archetypes.

Now please edit the markdown file to add any post that you want if you want to follow my example. And that’s it, you are in a good way to start building your website using hugo.

Run locally

Now that the website starts to have some content, we can jump into running a webserver and access our html files from a web browser. Hugo also incorporates a handy command for this purpose, hugo run. But as you can see from the hellow-web.md file every new content that we add is marked as draft. So an special parameter to see draft content can be used, which is hugo run -D

$`hugo` serve -D
port 1313 already in use, attempting to use an available port
Start building sites …

                   | EN
-------------------+------
  Pages            |   8
  Paginator pages  |   0
  Non-page files   |   0
  Static files     | 118
  Processed images |   0
  Aliases          |   2
  Sitemaps         |   1
  Cleaned          |   0

Built in 14 ms
Watching for changes in /tmp/mywebsite/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /tmp/mywebsite/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: `hugo` server --disableFastRender
Web Server is available at http://localhost:41593/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Now you have a web-server running on your local machine under the port 41593, this may change from run to run depending on the availability of the ports on your machine. For that please take a look at the output from the command in this case the correct address is http://localhost:41593/. Finally, this is the content displayed in my web-browser.

Screenshot

What is next?

In the next part of this blog I will describe, how to uploading your page to the World Wide Web and how to configure the continuous deployment system form a git repository in github.com Next