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.
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.
We will be working locally, so we need to set up our local environment. Hopefully this part is as easy as one, two, three.
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.
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.
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: 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.
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:
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:
We can personalize our new site before deploying it. We will update the picture, the name, the color scheme, and the introduction text.
To update the name, and color scheme, add the following to your config.toml file:
[Author] name = "<your name>" [params.colors] background = "#4463AE" foreground = "#C8D6E9"
To update the introduction text, create a folder named “partials” under the “layouts” folder. Add a file called “introduction.html” that contains your introduction text to that folder.
If your site is looking like this you are on the right track:
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:
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.
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:
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.
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…”.
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.