Background

Over the years, the Black Marble blog server has been hosted on many platforms. It's previous incarnation was WordPress, running as a network of sites with an aggregated feed. Of late we had found this slow to serve the first page (due to website start-up time) and there was the constant need to keep the instance patched.

The time had come for a new solutions, and we picked Hugo Static Pages.

Migration Process

The process to migrate our content was not as hard as I had feared.

1. The main (aggregate of all active sites) blog was exported using Wordpress's export feature as an XML file.
2. The read only archives of blogs of ex. staff were individually exported, as they did not appear in the aggregate export file.
3. The exported XML content was converted to markdown using blog2md. Note: that a small edit was made to the blog2md tool to place the contents of each sub blog in a separate folder
4. I wrote a PowerShell script to add an alias entry to each file so the old Wordpress permalinks were still valid.
5. A new Hugo blog was created using the hugo-clarity theme as this was a nice clean blog style theme.
6. I copied the exported folders (created by blog2md) into the content folder of the new site
7. I copied the wp_content/uploads folder structure containing all the Wordpress uploaded images to the static folder of the new site. This allowed any images to be found without the need to edit the <image src=... settings in the post files.
8. Edited the Hugo site to
   • Update styles/images to our branding
   • Removed sample site pages we did not need
   • Add a data structure to define the blogs on our site e.g. name, titles, github IDs etc.
   • Created a page to list the blogs based on the new data file.
   • Edited the partial html blocks to render the RHS pane as we needed it.

The site could now be tested locally. The next step was to publish it to Azure.

Hosting

We had planned to use Azure Static Web Sites to do the hosting as these are cheap, fast and the process is well documented. However we had a problem, our site was too big.

The largest site allowed in Azure Static Web Sites is 500Mb, our blog site was over 1Gb with the numerous pages and associated image content. Hugo generated sites are not small.

This meant we had to host the site in an Azure Web Site, we picked a Linux one, set to run PHP8. This setting is required because the Linux Web Site must have some execution engine selected, even though you are not using it. In effect enabling nginx. If this is not done then the static pages are not shown. There is a further issue with this type of hosting, related to nginx's handling of trailing slashes in URLs. The fix suggested here addressed the problem.

The move to a Azure Web Site necessitated editing the Azure Static Web Site generated Azure DevOps Pipeline. We ended up with a Pipeline that

1. Clone the repo
2. Downloads the Hugo tools
3. Runs the Hugo command to generate the static pages
4. Zip's up the generated pages
5. Uses Bicep to build the Azure Web Site
6. Uses Zip deployment to push the pages to the site.

Summary

I am really pleased with this migration. We have ended up with a faster site with a far lower running and maintenance cost.

It was no where near as hard as I had feared, given we had a aggregated network of sites; and we managed to keep all the old permalinks with the exception of the RSS file with changed form /feed/ to /feed.xml, but I can live with that. We don't see much RSS usage these days anyway.

So all in all well worth the effort.