API Management / Development

Tutorial: Use Hugo to Generate a Static Website

6 Oct 2020 12:20pm, by

With no database backend, plugins, or even PHP to go along with it, the open source Hugo uses templates to generate a full (albeit static) website. These pre-built pages are served up incredibly quickly. So when you need speed, Hugo could be what you’re looking for. Even better, Hugo includes its own built-in web server (for testing). You can host Hugo on the likes of:

  • Amazon S3
  • Azure
  • GitHub Pages
  • GoDaddy
  • Google Cloud Storage
  • Rackspace
  • Netlify
  • And more

Hugo uses TOML and YAML files for configuration, so most everyone that has worked with containers should have a modicum of familiarity with the language. Hugo also uses markdown for pages that are created.

I’m going to walk you through the process of installing Hugo and then generating a static website. You’ll be surprised at how simple it is. Once you have the basics of Hugo down, you can then attempt to insert it (should you need) into your CI/CD pipeline.

I’ll be demonstrating on Ubuntu Desktop 20.04. However, if you’re a macOS user, you can also install it with Homebrew and MacPorts.

Installing Hugo

Hugo can be found in the standard repositories, so installing it is as simple as logging into your desktop, opening a terminal window, and issuing the command:

sudo apt-get install hugo -y

Once the installation is complete, you can issue the command hugo –help to ensure the installation was successful.

You will also need Git installed on your machine, so issue the command:

sudo apt-get install git -y

Of course, you could install them both with the command:

sudo apt-get install hugo git -y

Create a Static Site with Hugo

Now the fun begins. Here’s how it works:

  • You first use Hugo to generate all of the elements you need for your site.
  • You use git to initialize the root folder and then pull down a theme for the site.
  • You then launch the site locally.
  • You can then modify the site content to fit your needs.
  • Once the site is exactly how you want it, you then build the site.
  • Once the site is built, you can then push it to your host.

At this point, you’re probably saying to yourself, “But I can build a site like that with HTML and other web-friendly languages just as easily. Of course, you can. Consider Hugo like a framework for building websites. With that in mind, all you then have to do is add the content (not the code) and you’re up and running. So using this tool can be more efficient.

Let’s walk through the process.

Step 1: Generate the Site

First we use Hugo to generate the bones for the new site. For that we’re going to create the site newstack with the command:

hugo new site newstack

That should complete in the blink of an eye. You will now have a new directory for your site. Change into that directory with the command:

cd newstack

If you issue the ls command you’ll see six folders (archetypes, content, data, layouts, static, themes) and one file (config.toml).

Step 2: Download a Theme

Next, we’re going to use Git to add a theme to the site. Before you do this, head over to the Hugo Themes repository and select a theme you like. I’m going to demonstrate with the Hugo Coder theme.

First, we need to initialize the root folder with the command:

git init

Next, we’ll add the theme as a Git submodule with the command:

git submodule add https://github.com/luizdepra/hugo-coder.git themes/hugo-coder

Each Hugo theme includes a full working website, so in order to make use of it, you must copy all of the content out of the theme folder into the root directory of the new site. To do this, change into the newly cloned directory with the command:

cd themes/hugo-coder

Next, copy all of the content into the root directory with the command:

cp -rf * ../../

Change back into the root directory with the command:

cd ../../

If you issue the ls command, you should now see all of the content from the theme found in the root directory.

Finally, we need to copy the Hugo Coder config.toml file into the root directory with the command:

cp exampleSite/config.toml .

Step 3: Launch the Site Locally

For our next trick, we’re going to launch the site on the local machine. To use the Hugo built-in server, launch the site with the command (from the root directory):

hugo server -D

Open a web browser and point it to http://localhost:1313 and you should see the new site presented with the Coder theme ready to configure.

Our first site built with Hugo.

You should also see, in the command output, how fast the site was built. In my case, it was created in 257 ms. That’s fast.

Currently, the site is a working copy, served from the local machine’s RAM. The Hugo server is running in demon mode and is watching the config.toml file for changes. Open a second terminal and change to the site’s root directory. Open the site’s TOML file with the command:

nano config.toml

Change the baseURL to either the domain or the IP address for your server and change any other bits and pieces you like:

Editing the config.toml file for the new Hugo site.

Once you’ve modified the config file, save the file with the [Ctrl]+[x] key combination and you should notice that Hugo will detect the changes and refresh the site to reflect them :

The changes are automatically reflected in the running site.

Obviously, some of the themes will include more sample content to use as a guide. But once you’ve downloaded and explored enough themes, you can start building your own themes. What’s important, however, is that as you change a theme (while Hugo is running in local daemon mode), the changes will be reflected in real-time, as you save the config file.

How to Create New Content

With the Hugo Coder site, you’ll need to copy the exampleSite/content directory into the root directory with the command:

cp -rf exampleSite/content/* ./content

How you create content for your site will depend on which theme you use. But generally you create new content with a command like:

hugo new content/posts/blog-post-1.md

Once the page is created, you can then edit it with the command:

nano content/posts/blog-post-1.md

Edit the content of the new file as you need. Save and close the file and Hugo will automatically detect the change of the newly added blog post:

Our new blog post

Of course, how you integrate it into the site will depend on the theme chosen.

Once you have the site exactly how you want it, kill the daemon server with the [Ctrl]+ keyboard combination and build the site with the command (run from the root directory):

hugo

The site will very quickly build and create a new public folder inside the document root. Upload that folder to your hosting server and you’re good to go.

Conclusion

And that’s the gist of creating a static website with Hugo. Once you have the hang of this, you can start dreaming of ways to integrate it into your CI/CD pipeline. Or, you could simply use it as a tool to very quickly generate static websites, based on a template of your own creation. Either way, Hugo is a powerful tool to have in your developer toolkit.

A newsletter digest of the week’s most important stories & analyses.