10 Tips for Building and Deploying Hugo Websites on Azure Static Web Apps
Tags: azure, serverless, beginners, staticwebapps
Published: 2020-05-20 12:42:24

---
title: 10 Tips for Building and Deploying Hugo Websites on Azure Static Web Apps
published: true
description: After many Hugo deployments, here are some important “tips” that will help you get started hosting Hugo sites on Azure Static Web Apps faster and with confidence
tags: azure, serverless, beginners
---

I have a "**problem**".  
I buy domain names. 

The guilt I feel isn’t from buying the domain so much as getting the email that GoDaddy’s auto- renewal has once again garnished my wages for a domain I haven’t even thought about in year. 

I won’t share just how many domain names I own but I do know that I’m not alone in this addiction. 

We’ve all come up with an amazing idea to immediately snag the TLD (top level domain) before anyone else thinks of it. The number of domains I’ve bought while still dripping wet from the shower is north of 10, easily. This year! (just kidding ... I think 🤔) What month is it again? 

With a little extra free time and domains stacking up like the empty Amazon boxes in my garage, I decided to at least give each brilliant idea a landing page - a first step towards solving my domain dilemma AND the world's problems with answers to questions like [ShouldIWearAMaskAroundOthers.com](https://www.jhand.dev/swa18)? 

If you’re thinking to yourself -  
	“I wonder if he bought that domain just for this post?” 

… see how the **“problem”** works?

I’ve been a huge fan of the static HTML generator Hugo for years. First exposed through the Devopsdays community, I have used it for literally everything.  From my personal website, the podcast I co-host, and many other projects, Hugo has been my hammer of choice.  
 
Then I found out Microsoft would be announcing [Azure Static Web Apps](https://www.jhand.dev/swa08) at Build this year and I jumped at the chance to get early access. 

![Azure Static Web Apps](https://jhandcdn.blob.core.windows.net/blob/static-web-apps.png)

I kid you not – in less time it took Dominos to bring me my 2nd cheese pizza this week, I had live sites for MY custom domains including free SSL (Secure Sockets Layer) certificates.  

Incredibly pleased with my newfound sense of productivity, I began jotting down some of the things I ran into in case others are looking to find homes for their own orphaned domain names. 

📌 **TL; DR - After many Hugo deployments, here are "10 Tips” I have to help you host Hugo sites on Azure Static Web Apps faster and with confidence.** 

## Prerequisites 

Everything I’m going to show you moving forward assumes the following: 

- ✅ You have an Azure account ([sign up for free](https://jhand.dev/free)) 
- ✅ You have a Hugo site stored in a GitHub repo you own 

Already have an Azure account?  -- 🔗 **[Deploy from secret link](http://aka.ms/trystaticwebapps)**

![Static Web App Preview](https://jhandcdn.blob.core.windows.net/blob/StaticWebAppPreview.png)
Once you’ve entered the basic information and moved on to the initial build settings you will find three fields to review in the initial workflow file: **App location**, **Api location**, and **App artifact location**.

![Build Parameters](https://jhandcdn.blob.core.windows.net/blob/PlainHTML.png)

## 📌Tip #1 -The Initial Deployment May Fail 

The correct settings for your Hugo site depend on many factors, so don’t be surprised if the first build fails. Some themes require specific conditions to be met to build correctly.

During your first deployment, a file named **`azure-static-web-apps-xxxx.yml`** containing information for a GitHub Action will be created and added to the master branch of your Hugo repo. After synchronizing your repo with your local machine, you can edit the file.

With only 50-ish lines, it’s not too scary. However, it took me a few attempts to spot an improper indention in the file that definitely “*mattered*.”

![It Mattered](https://jhandcdn.blob.core.windows.net/blob/TwitterItDid.png)

Don’t get discouraged if you find a big red **X** next to your first GitHub Action. 

 ![Failed Build](https://jhandcdn.blob.core.windows.net/blob/failedbuild.png)

For example, the [Academic-Kickstart theme](https://www.jhand.dev/swa03) I use for “[On-call Life](https://www.jhand.dev/swa04)" requires Hugo to build the site with the “**extended**” flag as shown below.

```yaml
    - uses: actions/checkout@v2
      with:
        submodules: true

    - name: Setup Hugo
      uses: peaceiris/actions-hugo@v2.4.8
      with:
        hugo-version: "latest"
        extended: true
        
    - name: Build
      run: hugo
      extended: true
```

## 📌Tip #2 - App Location Should Be Set to Public (but not always)  

This is where your static files will be stored and served behind the scenes. In most cases, **public** should be correct but not always. 

Some themes require specific entries in the **config.toml** file that may be different from a super simple Hugo site like the one in the [online tutorial on Docs](https://www.jhand.dev/swa10). 

The [Slate theme I used](https://www.jhand.dev/swa06) for “[Jhand.TV](https://www.jhand.tv)” publishes and serves the HTML content out of the **docs** directory by default (rather than public). 

![Not Public Directory](https://jhandcdn.blob.core.windows.net/blob/WhenHugoArtifactFolderIsn'tPublic.png)

 To get my site to build, I updated the **app_location** entry in my workflow file to the following and everything was smooth sailing from there. 

```yaml
        app_location: 'docs' # App source code path
        api_location: '' # Api source code path - optional
        app_artifact_location: '' # Built app content directory - optional
```

## 📌 Tip #3 - Api Location Should Be Empty 

Hugo sites rarely include a directory named **api** by default.  

If you notice a warning in GitHub Actions complaining about a missing api location, it’s probably because you left the default text in the parameter field during the initial deployment. Unless you have a directory in the root of your repo named **api**, you can leave this empty.  
 
Although you can force GitHub Actions to ignore the api directory by removing it from the yaml workflow file, if you create a directory named **api** with a README.md file it won’t generate an warning message during the build step. 

## 📌 Tip #4 - App Artifact Should Be Empty 

This one can be a little confusing. For *most* static web apps, an “artifact” is created during the build process which is then deployed.  

In the world of Hugo, our only “artifact” is the collection of html, CSS, and JavaScript files that were outputted to the public folder I mentioned in Tip #2. However, that is not what this field is asking for.  

If you happen to put public in by mistake or just because you like to poke at things and understand what happens (like me), it will complain in the GitHub Action logs if you don’t have a public folder. Just like in Tip #3 with the api folder, you can silence the error by pointing to an empty public folder. 

## 📌 Tip #5 - Leave Your Public Folder (inside Hugo) Out of This 
Anyone who has worked with Hugo knows that when you build the site locally, all HTML, CSS, and miscellaneous files are placed into a directory within the Hugo directory synchronized with your Hugo repository on GitHub. Usually the directory is public, but as mentioned in tip #3, not always. 

This means that if the public directory exists locally when you push your files, you will be transmitting everything in the public folder (or similar) even though it is not needed.  

GitHub Actions is going to rebuild the site each time there is a change to the branch. Because of this, it’s best to either remove any public folders in your Hugo directory OR put it in your .gitignore file.

## 📌 Tip #6 - There Can Be Only One Workflow 
Be sure to remove any old yaml files created that may still be loitering in your **.github\workflows** directory from earlier deployment attempts from earlier deployment attempts. 

Although they technically won’t cause a problem with the deployment of your current site, GitHub Actions will still attempt to run the old CI/CD workflow. Because the yaml file references old resources that likely no longer exist, errors will occur, and the build associated with the previous workflow will fail.  

## 📌 Tip #7 - Mind Your Size 
There is a **100Mb** size restriction for deployments.  

When trying to deploy [JasonHand.com](https://www.jhand.dev/0) I had many of my images in the repo on GitHub. Even though none of them were exceptionally large and my image directory rarely changed, when Hugo built the new site it used the images stored inside my Hugo directory which collectively exceeded the 100Mb limit. 

Here is the error message I get when Azure Static Pages tries to build. 

![Too Big](https://jhandcdn.blob.core.windows.net/blob/TooBigDeployment.png)

Once I moved all my images into blob storage on Azure and pointed the markdown files to those public links instead of assets inside my Hugo repository, the overall size of my build fell far below the limitations to build and deploy perfectly. 

## 📌 Tip #8 - Submodules 

Many themes require a reference to their original repository to properly build all the files for your site. If the theme you are using includes a step of `git submodule`, you are in this situation. 

The default workflow file takes submodules into consideration but in some cases, you may need to create a **.gitmodules** file in your repository. 

```yaml
[submodule "themes/hugo-elate-theme"]
    path = themes/hugo-elate-theme
    url = https://github.com/saey55/hugo-elate-theme
```

## 📌 Tip #9 - Just HTML 
What if you just want to deploy HTML?  

Regardless of how the site was built, if it doesn’t require any server-side processing, you can still take advantage of Azure Static Web Apps. 

Assuming the root directory of the GitHub repository is the root of the site, use the following in your yaml workflow file to skip the build process and deploy the files as a ready-to-go static site.  

```yaml
        app_location: '/' # App source code path
        api_location: '' # Api source code path - optional
        app_artifact_location: '/' # Built app content directory - optional
```

This is exactly what I did with [DevopsRoadtrip.com](https://www.jhand.dev/rt) and [ShouldIWearAMaskAroundOthers.com](https://www.jhand.dev/swa18).  

They are both simple HTML sites with an index.html, basic CSS, and some JavaScript.   

## 📌 Tip #10 - Learn More and Experiment 

Azure Static Web Apps is a new Azure service for deploying and hosting static web applications and sites built with Hugo, Gatsby, Jekyll, and many others. With my tips above I hope you too can find a home for all the amazing domain ideas you came up with. 

I've had a blast playing around with this new tool. Having the ability to deploy and host my Hugo sites just by pushing code to my GitHub repo AND have it point to my own custom domain with SSL is a game changer for me. I suspect it might be for you!

I can't wait for you try it out yourself. Experiment and [let me know what you think](https://twitter.com/jasonhand).

## Resources

Check out some of the documentation, tutorials, and resources currently available at the release of Azure Static Web Apps in Preview.

- 📔 [Docs](https://www.jhand.dev/swa08) 
- 📏[Microsoft Learn](https://www.jhand.dev/swa09)
- 📋 [Hugo tutorial](https://www.jhand.dev/swa10) 
- 📋 [Gatsby tutorial](https://www.jhand.dev/swa11) 
- 🌅 [Sunrise Standup Demo Application](https://www.jhand.dev/swa12) 
- 🙏 [Community Kit](https://www.jhand.dev/swa13) 
- 📺 [Learn TV](https://www.jhand.dev/swa14) 

### Hugo Sites I moved to Azure Static Web apps 

- 🔗 [SnackableCloud.com](https://www.jhand.dev/swa15) 
- 🔗 [On-Call-Life.com](https://www.jhand.dev/swa16) 
- 🔗 [Jhand.tv](https://www.jhand.dev/swa17)
- 🔗 [ShouldIWearAMaskAroundOthers.com](https://www.jhand.dev/swa18) 
- 🔗 [DevopsRoadtrip.com](https://www.jhand.dev/swa19) 
- 🔗 [JasonHand.com](https://www.jhand.dev/0) 
- 🔗 [CommunityPulse.io](https://www.jhand.dev/swa02) 
- 🔗 [MileHighBluegrass.com](https://www.jhand.dev/swa20)