Migrated to Hugo and Static WebApps

Migrated to Hugo and Static WebApps

Hugo, Static WebApps and GitHub Actions

Sterling Hammer
Guides
Page content

If you saw my previous article, why I chose Hexo for my Technical Blog you may be wondering, why the move to Hugo now?

I’m not going to spend a ton of time recapping all of the various options as I already did that in the previous article. Hugo was the close second last time around, I even mentioned it could be a coin flip!

I spent a bit of time kicking the tires on Hugo for some test projects and really liked how the templating worked. I was also a fan of the various themes that were out there and available and decided to go with Mainroad which I’ve modified a bit to suit my needs.

I also wanted to check out a few other things - which finally caused me to make the switch!

  • Azure Static Web Apps - This was launched a while back, and I’ve been following it since. I was previously using Static website hosting in Azure Storage. It has some nice integration I wanted to try which brings me to…
  • GitHub Actions - I’ve not had the opportunity to use it yet, and since it has direct integration with Static WebApps - it was an opportunity kick the tires.

So switching to Hugo has given me the chance to check out three new pieces of tech! Hard to argue with that!

I’ll go a bit into detail on the process and steps I took to make it happen.

Moving to Hugo

The majority of the work moving to Hugo was finding a theme I liked and migrating the content over. I didn’t find any way to automatically do this so I just ended up moving over all the content manually.

Fortunately, I do not have a lot of posts so it was just a few hours of work to create the new articles in Hugo and then paste over the content from my Hexo installation. Everything is still in markdown so it was just a matter of changing over some front matter.

Once all that was done, I spent most of the time customizing the Mainroad theme to my liking. Let me know if you’d like to see a blog on that!

Moving to Static Web Apps & GitHub Actions

The remaining piece was to stand up a new Static WebApp and link it up with everything else. Below is a high level guide on how to create a Hugo site, Static WebApp and deploy it using Actions.

Create Hugo App

  1. Install Hugo locally
  2. Create a new site using hugo new site <sitename>
  3. This can be done at any point during the steps, but you’ll want to initialize a Git repo utilizing git init within the site directory. If you’re unfamiliar with this process check out this guide on GitHub. I personally do not utilize GitHub Desktop, but it’s not a bad option if you’re new to git.
  4. You’ll need a theme at this point to proceed. themes.gohugo.io is a great place to start. Each theme will have instructions on how to install and configure it.
  5. Customize the theme to your liking. All of this work can be done locally by running hugo serve, any changes you make will be reflected in your local browser.

Push to GitHub

Once you have completed your site and customized the theme to your liking you’ll want to push it out to GitHub so that you can later setup a Static WebApp and GitHub Action.

There are a number of ways to go about this, I’m going to cover how it would be done via command line. But you can also push your local repository to GitHub directly from VS Code.

  1. Create a GitHub Repo at https://github.com/new
  2. Name it the same as the <sitename> you picked above. So if you named your app MyHugoApp you’ll want to create a MyHugoApp repository.
  3. Add the newly created repository as a remote to your local repo. git remote add origin https://github.com/<YOUR_USER_NAME>/MyHugoApp
  4. Finally, push your repository up to GitHub git push --set-upstream origin main

Deploy your WebApp

The below steps assume you’ve already created an Azure Subscription and have a basic understanding of Azure.

  1. Head to the Azure Portal
  2. Select Create a Resource
  3. Search for Static Web Apps
  4. Select Static Web App
  5. Select Create
  6. On the basics tab, fill out all of the relevant fields.
    • Subscription
    • Resource Group
    • Name
    • Plan Type
    • Region
    • Source - Set to GitHub
  7. Select Sign in with GitHub, at this point you’ll select your Organization, Repository that you created above and your branch. This could be either master or main depending on what you selected during installation of git.
  8. In the Build Details section select Hugo from the Build Presets drop-down and select the default values.

Create and Deploy

The last phase will be to review the settings and create the WebApp which will trigger the new GitHub action to run and deploy your new app!

  1. Select Review + Create button to verify everything you filled out is correct.
  2. Select Create to start the deployment of your App Service and provision the GitHub action for deployment.
  3. When the deployment completes click Go to resource.
  4. Once on the resource screen click the URL link to open up your deployed application. It may take a few minutes for the GitHub action to complete.

That’s it! Your app should now be deployed. A more detailed version of the high level guide above is available on Microsoft Docs.

Custom 404 Page

You may want to setup a custom 404 page with your Hugo app. If you don’t do this, you will get a generic 404 page. The good news is, this process is pretty straightforward. Many templates, including Mainroad include a 404 page which will be at /404.html - all you need to do is add a file called staticwebapp.config.json to the /static directory in your Hugo app. The content should be as follows:

{
  "responseOverrides": {
    "404": {
      "rewrite": "/404.html"
    }
  }
}

Once this is complete, and deploys via your action - there will be a custom 404 redirect any time someone hits a bad link on your site.

Conclusion

Now any time you make an update to your blog, commit it in git and sync it up to GitHub your new action will trigger and deploy out to your website! From here you may want to set up a custom domain or even do a custom 404 page.