iconic sections

discord and hyperbole

How to build your static site with Hugo

Posted on Jul 15, 2019

In a pair of previous posts I described how to host a static site in Azure storage and also how to use a CDN to map a custom domain to your site with https. For each of those examples I used a simple ‘hello world’ html page, but in the real world we are going to want more out of our site. In my research I came across Hugo and decided to give it a go.


What is Hugo?

Hugo is an open source static site generator. If you really want to be sold on it, go browse their docs to learn everything you might want to know. As an end-user, Hugo feels great because:

If you are interested in giving it a try, then read on.


Prerequisites

We will be working locally, so we need to set up our local environment. Hopefully this part is as easy as one, two, three.

Code Editor

Since we will be working on our site locally and deploying it to Azure, we will need a code editor. I prefer to work with Visual Studio Code, so we will use that for this example.

Step one is to download and install VS Code.

There are a number of useful extensions you can install for VS Code, but the one we will use for this example is the Azure Storage extension, which will allow us to update our static site on Azure right from our editor.

Step two is to download and install the Azure Storage extension.

Hugo

Since we will be building out our site with Hugo, we will need to install it first.

Step three is to follow the instructions here to install Hugo and then come back.


Making a site with Hugo

Now we should be ready to build our our site with Hugo. I recommend opening VS Code and bringing up the terminal (either View -> Terminal, or ctrl-`). To confirm you have Hugo installed you can run hugo version. With Hugo installed, you can get started with the command:

hugo new site staticsite

This will create a new Hugo site in a folder named staticsite. From here we want to navigate to that folder and open it in our editor:

cd staticsite
code .

This will open a new instance of VS Code. It should look a little like this:

 vs code hugo project
Figure 1
You can see the structure of our Hugo site in the explorer window:

Although the scaffolding for the site is there, it doesn’t do anything yet. It lacks any implementation. While we could build it ourselves, we will take the easier route for the time being and use an existing theme.


Hallo

For our example, we will use the Hallo theme because it is simple and has an MIT license. To install it, first make sure you are in the staticsite directory we created earlier. Then run the following from the terminal in VS Code:

git clone  https://github.com/EmielH/hallo-hugo.git themes/hallo

You should now see a “hallo” folder under the themes folder. Open the “config.toml” file in your project and add the line theme = "hallo". Your project should look like:

 vs code hallo theme
Figure 2

Run the command hugo server from the terminal to launch your project locally. Navigate to the url provided for the web server to see your page:

 hallo theme
Figure 3

Update your site

We can personalize our new site before deploying it. We will update the picture, the name, the color scheme, and the introduction text.

If your site is looking like this you are on the right track:

 hallo updates
Figure 4

If you have kept your site running locally, check it out. If you stopped it, the simply run hugo server again to see the result:

 hallo updates
Figure 5


Publish to Azure

Now that we have our site looking the way we want, all that is left it so publish it to Azure. This process is quick and easy.

Step One: Build your Hugo Site

First we need to build our proud Hugo site. From our the root “staticsite” folder we have been working on navigate to the terminal in VS Code and run:

hugo

This command will run very fast. If you look closely, you will notice a new folder named “public” in your project. This project contains the static version of your Hugo site.

Step Two: Deploy to Static Website…

If you right click on the new “public” folder in the Explorer pane of VS Code, you will see an option to “Deploy to Static Website…”.

 deploy
Figure 6

This option was included with the “Azure Storage” extension we installed earlier. After you click it you will see a follow-up dialog to pick a Storage Account. Choose the one you created in our previous walkthrough. You will likely be prompted to delete the files that exist in your site and deploy the new ones. Choose yes and wait for your site to be copied.


That’s it. You should now be able to see your new Hugo site hosted on Azure. If you mapped your site to a custom domain using a CDN, you should now also see it at that address. (If it doesn’t show up right away you might want to purge your CDN endpoint.)

There is a lot more you can do with Hugo, but I hope this has helped you get started.

Thanks!