HUGO, create static websites faster.

Let’s create a website using GO Lang based HUGO static site generator.

Photo by Safar Safarov on Unsplash

HUGO is a GO Lang based Static Site Generator (SSG) and they call it as world’s fastest website framework for designing websites. So let’s dig into it and find out if it’s really that fast. ⚡️ ⚡️

Static websites are the integral part of the internet. Anyone who want’s to have an online presence say an individual or a business starts with a static website. Things have been evolving in terms if web development. There have been various tools to write HTML and CSS, for HTML we have PUG and for CSS we have SCSS, LESS, STYLUS. The new tools helps the developer/designer for faster development. In the same duration the tools such as Gulp / Grunt were introduced to automate the workflow. But its been quite some time that static site generator has come into picture. Few of the major SSGs are Gatsby, Next Js, Jekyll and so on.

We will using a Windows 10 OS for development.

HUGO installation 🚀

You can download the the latest HUGO release from the GitHub page: link. We have two versions for HUGO normal and extended. If you want a inbuilt SASS/SCSS compiler you can opt in for the Extended version.

HUGO versions

Here we select the extended version as we need a SASS/SCSS compiler for our project.

Next, create a folder in root of your C:/ or where you have installed your OS named as “Hugo”. Inside “Hugo” create another folder names “bin” and extract the files from the zip file you downloaded.

C:/
|-- Hugo
|   |-- bin
|       |-- hugo.exe
|       |-- LICENSE
|       |-- README.md

We need to add Hugo to your Windows PATH settings.

1. Open Environmental Variables.
2. Double-click on PATH.
3. Click the New… button.
4. Type in the folder where hugo.exe was extracted, which is C:\Hugo\bin if you went by the instructions above. The PATH entry should be the folder where Hugo lives and not the binary. Press Enter when you’re done typing.

Installation is now complete you can check by Hugo version command. ⭐️

C:\Users\Prajkt>hugo version
Hugo Static Site Generator v0.74.0/extended windows/amd64 BuildDate: unknown

You will have similar kind of output.

Create New Site ✏️

Create a folder named Sites in the Hugo folder.

C:/
|-- Hugo
|   |-- bin
|   |-- Sites

Navigate to Sites folder and lets create a new site here by -

hugo new site hugo-starter

You have your new HUGO website ready inside the sites folder and you will find the following files in hugo-starter folder.

hugo-starter
|-- archetypes
|-- content
|-- data
|-- layouts
|-- static
|-- themes
|-- config.toml

Directory Structure 📁

Lets go through the folder structure, will help in easy understanding. Below content is from the HUGO officaial documentation.

Archetypes

You can create new content files in Hugo using the hugo new command. By default, Hugo will create new content files with at least date, title (inferred from the file name), and draft = true. This saves time and promotes consistency for sites using multiple content types. You can create your own archetypes with custom preconfigured front matter fields as well.

Assets

Stores all the files which need be processed by Hugo Pipes. Only the files whose .Permalink or .RelPermalink are used will be published to the public directory. Note: assets directory is not created by default.

Config

Hugo ships with a large number of configuration directives. The config directory is where those directives are stored as JSON, YAML, or TOML files. Every root setting object can stand as its own file and structured by environments. Projects with minimal settings and no need for environment awareness can use a single config.toml file at its root.

Many sites may need little to no configuration, but Hugo ships with a large number of configuration directives for more granular directions on how you want Hugo to build your website. Note: config directory is not created by default.

Content

All content for your website will live inside this directory. Each top-level folder in Hugo is considered a content section. For example, if your site has three main sections—blog, articles, and tutorials—you will have three directories at content/blog, content/articles, and content/tutorials. Hugo uses sections to assign default content types.

Data

This directory is used to store configuration files that can be used by Hugo when generating your website. You can write these files in YAML, JSON, or TOML format. In addition to the files you add to this folder, you can also create data templates that pull from dynamic content.

Layouts

Stores templates in the form of .html files that specify how views of your content will be rendered into a static website. Templates include list pages, your homepage, taxonomy templates, partials, single page templates, and more.

Static

Stores all the static content: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the static folder is for verifying site ownership on Google Search Console, where you want Hugo to copy over a complete HTML file without modifying its content.

Website Layout 📜

You can run the hugo project using hugo server — D command, HUGO comes with LiveReload built-in. There is no need to install any additional packages. You can access through http://localhost:1313 in your browser.

Now, create a index.html file in layouts folder and have your default html5 code in it.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Hello Hugo Starter</title>
</head>
<body>
  <h1>Hello World</h1>
  <footer>
    Copyright 2020, All rights reserved to {{ .Site.Title }}
  </footer>
</body>
</html>

This is basically the landing page of the website. Now, lets breakdown the structure and make the code more modular.

Create a folder _default in the layouts folder. Create a file named baseof.html and move the html code form index.html to baseof.html .

You will see the similar output in the browser. Lets make it more modular. Lets separate out common components such as header, footer, navigation.

Create a partials folder in Layouts . For now we will separate out header and footer. So, create header.html & footer.html in the partials folder and add the data from the baseof.html file.

header.html
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ .Site.Title }}</title>
</head>
footer.html
<footer>
Copyright 2020, All rights reserved to {{ .Site.Title }}
</footer>

We have added {{ .Site.Title }} , this variable we will be accessing from the config.toml file and for individual pages we will be accessing it from the front-matter.

Now, create another folder _default in layouts folder and create a file named baseof.html

<!DOCTYPE html>
<html lang="en">
{{- partial "header.html" . -}}
<body>
  {{- partial "navigation.html" . -}}
   {{- block "main" . -}}{{- end -}}
  {{- partial "footer.html" . -}}
</body>
</html>

Here, you can see {{- block "main " . -}} {{- end -}} a block has been added, this block refers data from the index.html page. Now, declare the block in index.html file also. For more information on base and block template refer documentation .

{{ define "main" }}
  <h1> this is the home page</h1>
  {{ .Content }}
{{ end }}

{{ .Content }} will get the content from the markdown file. So let’s create a file for home page i.e _index.md in /content folder.

---
title: home
---
# this is index data from md file

Output

Styling HUGO website 🎄

We will add a SCSS file along with that we will use Boostrap as the base framework. I will be using Bootstrap’s latest version i.e Boostrap 5 Alpha.

1. Scss file
   As we are using the HUGO extended version, it will automatically sompile the scss into css file.
   We need to create a folder in the root /assets/scss/template.scss . We will write our scss code in template.scss file. So till now we have the following folder structure.

|   config.toml
|---archetypes
|       default.md
|---assets
|   |--scss
|      |--template.scss  
|---content
|       _index.md
|---data
|---layouts
|   |  index.html
|   |--partials
|   |  |--footer.html
|   |  |--header.html
|   |--_default
|       |-- baseof.html
|       |-- single.html
|---resources
|---static
|---themes

We need to import the scss file in header.html . The resources.Get will import the file from /assets/scss/template.scss . toCss will compile the scss into css, minify will help us for the optimization part, fingerprint helps for fingerprinting of the asset.

{{ $style := resources.Get "scss/template.scss" }}
{{ $style = $style | toCSS | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}">

Let’s try out something . Make sure you restart your server to make SCSS working.

Working SCSS in HUGO website

2. Bootstrap Import

You can use the bootstrap CDN links and import in header.html file.

<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ .Site.Title }}</title>
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/5.0.0-alpha1/css/bootstrap.min.css" integrity="sha384-r4NyP46KrjDleawBgD5tp8Y7UzmLA05oM1iAEQ17CSuDqnUK2+k9luXQOfXJCJ4I" crossorigin="anonymous">
{{ $style := resources.Get "scss/template.scss" }}
{{ $style = $style | toCSS | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}">
</head>

Once you have imported the CSS and the JS file, you can start using boostrap components.

More Pages 📄

Lets create few more pages say About Us and Contact Us. Before creating more pages you should know the templates that HUGO uses. So there are 3 types of templates used for strucutre -

• List Template- As Hugo docs states “Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list.”
• Single Template — As Hugo docs states “The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template.”
• Home Template — As Hugo docs states “The homepage of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site’s homepage as a unique template.”

Lets create 2 different layouts for About Us and Contact Us and also create two respective markdown files for content in /content folder.

|   config.toml
|---archetypes
|       default.md
|---assets
|   |--scss
|      |--template.scss  
|---content
|       _index.md
|       about.md
|       contact.md
|---data
|---layouts
|   |  index.html
|   |--partials
|   |  |--footer.html
|   |  |--header.html
|   |--_default
|       |-- baseof.html
|       |-- single.html
|   |--about
|       |-- single.html
|   |--contact
|       |-- single.html
|---resources
|---static
|---themes

Add some content in the md files.

about.md
---
title: About Us
type: about
---
# this is about us from md file

contact.md
---
title: Contact Us
type: contact
---
# this is contact us from md file

The type here is used to define the layout as for About Us we have used /layouts/about .

We need to decalare the main block in 2 newly created layouts as well.

about/single.html
{{ define "main" }}
   <h1> this is the about page</h1>
   {{ .Content }}
{{ end }}

contact/single.html
{{ define "main" }}
   <h1> this is the about page</h1>
   {{ .Content }}
{{ end }}

Routing in HUGO

I guess now you have got the idea about templates and hugo framework works. The further development will be creation of navbar which will consist of menu items.

For Blogs, we will have to use 2 layouts, one is the list template to generate list of blogs and other to have a detailed view of the blog.

You can find all the above code along with blog view and navbar in the gitlab link shared in the end of the project along with the hosted project link.

Deploy Your Website ☁️

Use command hugo this will generate a new directory /public . This folder is ready to be deployed. Use HUGO deploy documentation for various options.

I personally use Digital Ocean droplet with NGINX as my web server, you can easily create a virtual block and assign a domain to it .

The final verdict is, yes HUGO is blazing fast ⚡️ ⚡️ ⚡️ . There are lot of features that i have not covered in this article but do refer the hugo docs. I think this can replace the existing gulp/grunt or Jekyll projects mainly because of its speed.