Thanks to the tool wp2hugo the migration was really smooth. Follow along, step by step.

Install Hugo

I’m on a Mac and use Homebrew. If you don’t, there are other ways of installing Hugo. Should be fairly easy, whether you use macOS, Linux, Windows or BSD.

This is what I had to do to install Hugo:

brew install hugo
Screenshot of shell when installing Hugo with Homebrew

This is how easy it is to install Hugo. I already had Hugo installed, but ran the command to show you. Luckily, an update was available so I actually had something to show.

Checked it works:

hugo version
Screenshot of shell when running 'hugo version'

OK, we’re good.

Export the WordPress content

Using the default export tool in WordPress.

  1. In your dashboard, head down to Tools > Export in the main menu.
  2. Make sure you export all content.
  3. Download the export file.

This should go fairly quickly. I got a 2.9 MB XML file named bjrnjohansen.WordPress.2024-10-15.xml.

Screenshot of exported XML file

This is what the XML file looked like. We don’t have to touch anything in it.

For easier reference further down, let’s say I renamed the downloaded file to wordpress.xml.

Download wp2hugo

I am so happy, I found the tool wp2hugo by Ashish Bhatia. Looks like he recently was in the exact same position as myself, wanting to migrate from WordPress to Hugo, and wrote this tool to deal with it.

You can use wp2hugo to setup a Hugo site, convert all WordPress posts and pages as markdown files, and automatically download all media in those posts and pages.

First, head over to the wp2hugo releases on GitHub, download the file for your platform and extract it. I copied the executable file wp2hugo over to the same directory where I put my wordpress.xml.

Screenshot of directory containing only the wordpress.xml file and the wp2hugo file

An empty directory, with all the files we need to get started.

Note: To be able to run the executable file wp2hugo on macOS, you may have to browse to the dir in Finder, right-click the file and choose to open it in Terminal. This is because of a security feature in the OS which prevents users from executing files from origins Apple doesn’t know about.

Run the migration tool

First, make sure you have an empty directory to store your new site. I just created a new dir named output:

mkdir output
Screenshot of directory containing the wordpress.xml file, the wp2hugo file and the empty output dir

The directory with files we need to get started, and an empty output dir.

Now, in the directory where you have the wordpress.xml and wp2hugo files, run the following command:

./wp2hugo --source wordpress.xml --download-media --output ./output
Screenshot of shell with the above command ready to run

Ready to run the wp2hugo migration command

You should now have your Hugo site in a timestamped subdir of the output directory.

The static files you can publish to any web host are found in the public subdir.

Add pages to the main menu

Apparantely there are more than one way to do this. I just had two pages to add to the main menu, so I opened those two files in an editor and added this line their front matter:

menus: main

Run Hugo server to test the site

Hugo comes with a server for local testing. Spin it up, and you can browse your site and see changes you do in realtime:

hugo server

Everything looked fine to me. Both YouTube and GitHub Gist embeds worked fine. Content from both the classic editor and from the Gutenberg looked fine.

Export the site as static files

This command exports everything you need to the public directory.

hugo

That’s it. Your entire static site is now in the public directory. You can upload this to your web host. You don’t need to upload anything from outside of the public directory.

Upload the static files to your web host

Since everything is static, I figured I could simply use Cloudflare Pages to serve the content. Then I found out that Cloudflare Pages in fact has Hugo installed, which makes it really easy to host your Hugo site on it.

Cloudflare has a tutorial on getting started with Hugo, and deploying to Cloudflare Pages. Since you already are started, you can skip down to Create a GitHub repository. Oh, and I also found out it was better to not configure the baseURL on the command line using hugo -b $CF_PAGES_URL as Cloudflare recommends, but just running hugo as normal.

Comments

As comments requires a comment system, wp2hugo doesn’t cover those. The author of wp2hugo recommends using Remark42. You can import comments to Remark42 from WordPress. Others have recommended using Artalk, which also has a migration tool to import comments into Artalk from WordPress.