From WordPress to Hugo: Migrating a 250+ Page Site

After running my blog on WordPress for several years, I recently decided it was time for a change. With over 250 pages of content, the thought of migrating to a new platform was daunting at first. But after weighing the pros and cons, I realized that moving to a static site generator like Hugo would provide major benefits in terms of performance, customization, and ease of use.

In this post, I‘ll share why I chose to migrate from WordPress to Hugo, walk through the process I used to export my content and set up the new site, and highlight some custom scripts I wrote to automate parts of the migration. I‘ll also share some of the key results and lessons learned.

Why Migrate from WordPress to Hugo?

WordPress powers over 40% of websites on the internet, and for good reason. It‘s user-friendly, extensible, and has a massive ecosystem of themes and plugins. So why would anyone want to move away from it?

For me, the decision ultimately came down to performance, flexibility, and simplicity:

• As a static site generator, Hugo builds your entire site as simple HTML, CSS, and JavaScript files. This makes it extremely fast and easy to deploy.

• Hugo is endlessly customizable. You have full control over your site‘s HTML, CSS, and layout without having to wrestle with convoluted WordPress themes and templates.

• All content is stored as Markdown files, which enables a cleaner writing workflow, easy version control, and portability.

• No backend server, plugins, or databases means less overhead to manage and a cheaper hosting bill. Static sites can be deployed almost anywhere.

I was also growing increasingly frustrated with WordPress‘s editor (Gutenberg), buggy plugins, and constant security updates.

After looking at the major static site generator options (Jekyll, Next.js, Gatsby, Hugo, etc.), I decided to go with Hugo for a few key reasons:

• It‘s written in Go and extremely fast. Builds take milliseconds instead of minutes.

• It has a large and active community with plenty of themes and starters to choose from.

• It doesn‘t try to do too much. This keeps the tool focused and easy to use.

• As a Go fan myself, I like the ability to enhance Hugo with custom Go code if needed.

With the decision made, it was time to start the migration process.

Exporting WordPress Content to Markdown

The first step was to get all my WordPress posts and pages exported into Markdown files with frontmatter that Hugo could understand.

Doing this manually would have been extremely tedious, so I used the Jekyll Exporter WordPress plugin to automate the process. Despite its name, this plugin works great for Hugo as well.

After installing and activating the plugin, I was able to export my entire site‘s content (250+ posts and pages) with a single click. The result was a zip file containing a Markdown file for each post/page, organized in directories by content type and date.

I did have to spend some time cleaning up the exported Markdown files, as the formatting wasn‘t perfect. I used a series of find-and-replace scripts to correct issues with image paths, shortcodes, and frontmatter syntax. But overall, this was still much faster than migrating the content manually.

Setting Up Hugo and Migrating Content

With my WordPress content exported, it was time to set up Hugo and import the Markdown files. I started by:

1. Installing Hugo
2. Creating a new site with hugo new site mysite
3. Adding a theme (I went with a customized version of the popular XMin theme)
4. Copying my exported Markdown files into Hugo‘s content directory

I then spent some time configuring the theme, customizing the layout, and setting up my own styles. This was made easier by Hugo‘s well-organized directory structure and straightforward templating syntax.

One of the great things about Hugo is that it provides built-in SEO templates for generating meta tags, XML sitemaps, and RSS feeds. So a lot of the on-page SEO foundations were already taken care of.

To further optimize the site, I took advantage of Hugo‘s minification features and caching to speed up the build and ensure that all resources were served as efficiently as possible.

Custom Scripts for Automation

As I started working with Hugo more, I realized there were a few tedious tasks that could be automated with custom scripts. So I wrote the following:

Script 1 – Broken Link Checker

This Go script crawls the entire site and checks for any broken internal or external links. It compiles a report of the errors so I can go back and fix them. (source code)

Script 2 – Image Optimizer

To optimize images without relying on a WordPress plugin, I wrote a Node.js script that automatically converts images to webp format, resizes them to a max width, and compresses them. (source code)

Script 3 – Shortcode Manager

This script allows me to bulk add or remove shortcodes from Markdown content programmatically. For example, I can use it to insert an email signup form after the 2nd paragraph in every post. Super handy for managing calls-to-action and other reusable snippets. (source code)

Script 4 – Word-to-Markdown Converter

To make it easier for non-technical writers to contribute content, I set up a script that converts Word .docx files to Markdown using Pandoc. This lets writers work in Word if they prefer, while still integrating with the Hugo workflow. (source code)

I‘ve open sourced all of these scripts on GitHub. Feel free to use or adapt them for your own projects!

Results and Takeaways

It‘s been over 6 months since I migrated my blog from WordPress to Hugo, and I couldn‘t be happier with the results:

• The site loads lightning fast. Most pages have a Lighthouse performance score of 100.

• Hugo‘s intuitive organization and templating have made it much easier to customize the site structure and design.

• I‘m saving $20/month on hosting costs now that I no longer need a beefier WordPress server.

• Writing content in Markdown and deploying the site via GitHub Actions has greatly streamlined the workflow.

• The custom scripts I wrote have eliminated some tedious manual tasks, and should keep saving me time.

Of course, the process wasn‘t without some lessons learned:

• Properly redirecting old WordPress URLs is critical for SEO. Don‘t underestimate how much traffic you can lose from broken links.

• WordPress RSS feeds can have some unusual quirks. I had to customize Hugo‘s RSS template to get it working smoothly.

• Analytics requires a bit more setup, since you no longer have plugins to rely on. I went with a self-hosted Plausible setup.

• There‘s still room for more automation. Next I might tackle automating image uploading and the publishing workflow.

Closing Thoughts

Migrating from WordPress to Hugo turned out to be a great decision. Not only has it made my site faster and easier to manage, it‘s provided a fun opportunity to learn some new technologies and flex my coding muscles a bit.

I will say that Hugo (and static sites in general) may not be the right choice for everyone. If your site requires dynamic functionality, complex user roles, or lots of server-side scripting, a CMS like WordPress could still be a better fit.

But for those who simply want a fast, flexible, and maintainable way to publish content, Hugo is an excellent option. I hope this post has given you a solid overview of what‘s involved in migrating to Hugo at a large scale.

If you have any other questions about making the switch, or suggestions on how to simplify it further, feel free to reach out!