Tutorial: Use Hugo to Generate a Static Website
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
- GitHub Pages
- Google Cloud Storage
- 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.
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:
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
First, we need to initialize the root folder with the command:
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:
Next, copy all of the content into the root directory with the command:
cp -rf * ../../
Change back into the root directory with the command:
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.
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:
Change the baseURL to either the domain or the IP address for your server and change any other bits and pieces you like:
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 :
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:
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:
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):
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.
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.