Hugo + Azure Static Web App + Azure GIT

April 18, 2023

To share the experience of developing www.bustit.app and drive traffic to the game we thought we'd blog about it. So we needed a platform to share the content. What follows is our solution and setup, hope it helps.

"Static Site Generator"

We are using Hugo to manage our blog content. There are plenty of good blogs / articles out there to set up Hugo and build out your website. Best place to start is the quick start on the official site.

At high level we can author our content as markdown documents in our editor of choice (we use Visual Studio Code), Hugo manages the generation of the site as static web content, themes, site maps, tags etc.

"Hosting"

Where were we going to host a simple blog site? Well with experience of hosting the main game under Azure Static Websites under our belt (more to share about that on a later date) again that seemed like an easy decision.

"Source Control"

We use Azure GIT, this is a private project and there are other examples out there using GitHub combined with Hugo and Azure Static Web Apps

Publish a Hugo site to Azure Static Web Apps

First step is to install Hugo for you OS. Follow the installation guide here
Open a terminal
Set your path to the location you are going to create your Hugo site
Run the following command where “NAME” is the name of your website
```
hugo new site NAME
```
Move you path to the site folder. Leave the terminal open, we will come back to it.
```
cd NAME
```
We need to create an new GIT repository through the Azure Devops website. See the guide here. Create repository without readme.txt deselecting the “Add a README” and .gitignore set to “None”.

You will be presented with the commands to push to the repository under “Push an existing repository from command line” copy these.

Back in your terminal initialize GIT, set the branch, and clone the default Hugo theme ‘ananke’

git init
git branch -M main
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke

Edit the default config.toml file in the route of your website, adding the theme reference “theme = ‘ananke’” so that your file will look like the following:
```
baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = 'ananke'
```
We add the first blog page.

From the terminal run:
```
hugo new posts/my-first-post.md
```
Edit the file under posts/content/posts/my-first-post.md. Remove the “draft: true” line to include it in the live site.
```
---
title: "My first post"
date: 2023-03-29T12:28:05+01:00
---
### Hello world! My first post
```
Lets commit this to the remote repo. Set the branch, and add the initial commit
```
git add -A
git commit -m "initial commit"
```
Add the relationship to the remote repository and push the content to the remote repository (this is the commands copied from Azure DevOps in step 6)
```
git remote add origin ###############################
git push -u origin --all
```
If you look at the route folder content in the GIT repo it will look like the following
```
> archetypes
> content
> resources
> themes
```
Next in the Azure portal create an Azure Static Web App. This is where we had to deviate from the tutorial Microsoft supplies. Following the step wizard you should be able to select your repo you created earlier and it should generate the site and associated Azure DevOps deployment pipeline. But you may get the error:

"Failed to create a Personal Access Token for this user in Azure DevOps. Please deploy your app using the ‘Other’ deployment source instead of ‘Azure DevOps’. After the app is created, open it and follow the instructions to get the token and deploy your app."

This is as we haven't connected our Azure DevOps to our Azure AD but we don’t want to and will go the manual route to create the pipeline and so clicked "Other" for the deployment source.

Once created copy the "deployment token " by selecting "Manage deployment token" from the "Overview" tab on the Static Web App.

Back in Azure DevOps create a new build pipeline. You will need to point the build pipe at your repository with the Hugo content and create a task to deploy to the new Azure Static Web App. You will also need a build agent associated to your project. Here's our pipe yaml.

trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: AzureStaticWebApp@0
  inputs:
	output_location: 'public'
	skip_api_build: true
	verbose: true
	azure_static_web_apps_api_token: '$(deployment_token)'

Notice the output_location is "public" this is default folder Hugo generates the website content to. We've also disabled the api build ("skip_api_build: true") as this is just static content. We need to create a variable "deployment_token" for our pipeline and paste in the token taken from the Azure portal.

When you run the pipe you may receive the error:

Run the pipe then bang no templates found for "pages"

WARN found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN found no layout file for "HTML" for kind "page": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN found no layout file for "HTML" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN found no layout file for "HTML" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

No index.html

This is because the pipe has not checked out the GIT sub module of admade, the Hugo theme. You will need to edit the build definiton “Get Sources” and select “Checkout submodules”, “Recursion level” as a value of “Top level submodules only”.

Create repo

Now when you run the pipe again the Azure Static Web App task will recognise the Hugo content and deploy to the resource.