A lot of people who migrated their sites from Wordpress to Hugo wrote about their experience. I gained a lot from reading those articles and hope my article will help you too.

As you read this article, the site is created with Hugo, a static site generator or SSG.

Here are my thoughts, lessons and tips after doing the migration.

Why Migrate

  1. The first reason for me to migrate is I wanted to upgrade my existing server running my Wordpress sites. The droplet on Digital Ocean has been running for 8 years and is in need of upgrade.

I was concern some part may be susceptible to hacking or something breaking.

It was something I wanted to do but put off for a long time because it involves a significant amount of work. That turned out to be true as you will read below.

  1. Why move to Hugo? I knew that migrating to a different server will involve many moving parts including moving 2 Wordpress sites, setting up a new server, nameserver changes, SSL certificates etc. I’ve done some of these before but others I need to figure out for example SSL certificates, hosting 2 sites on one droplet etc.

In the past, I used a server manager called ServerPilot and putting 2 sites on 1 server was quite easy. ServerPilot had a free plan which is no longer available & using their service or another server manager will cost the same as running 2 servers.

  1. Since migrating to a new server involved so much work, I decided to go the SSG route and use Hugo. Using a SSG meant I no longer need to manage a server, SSL is done automatic hosting the sites on Cloudflare or Netlify.

I initially used a plugin to turn everything into static html files and uploaded those directly to Cloudflare pages. It was a kind of a temporary solution until I figured out how to migrate the sites properly.

One site doesn’t need much updating while my main site JamesWoo.net is updated regularly.

Another thing is, one method of spinning WordPress on DigitalOcean requires having a domain name point to the process but I prefer a safer route of having everything in place before switching over.

Having done prior research, I dove in sort of head first and figured some things out along the way. Not the best way of doing things but with Hugo, I was able to test and do a lot of the things on my local computer before the actual site migration.

Pros

  1. The advantages after moving is my site is very much faster. In the past with WP, I use caching plugins and even Cloudflare to speed up the sites. This is even faster.

  2. I do not need to log in regularly to update themes and plugins eventhough I don’t consider updating those to be that big a hassle though. WP have been quite robust in that sense. It is just something to do occasionally.

  3. I no longer need to manage nor pay for a server. It is always nice to save a few dollars but managing the server is the bigger advantage for me. I no longer need to think about the need to upgrade the server in the future.

  4. I have less fear that my site will break or be hacked since it is all html, css and JS.

  5. Developing on my local computer or rather laptop. With Hugo, I can see my articles or changes on my local computer before uploading (or rather pushing the changes) to the server online. Hugo takes less than 1 second to generate the entire site on my local computer so I can work offline.

Cons

  1. As with such migration, it took a lot of searching, reading and understanding. It took longer than I expected. The reason is many things were new to me like using markdown language, VS Code, Git and Github, Hugo etc.

There were a number of new software and webiste that took to learn, understand and to use them. My knowledge is basic at best for things like html, css etc. eventhough I’ve tinkered with them in the past.

  1. After migrating, the process to write and post an article with Hugo is quite different. In a real sense, it takes more effort to add or update articles which you can read further down.

Key Points

I learn how to use Hugo on their website. Their tutorials are adequate but not the best.

I also learned a bit on installing packages via npm etc a few weeks prior to using Hugo as I took a few tutorials on Gatsby JS website. There, they cover things in greater details like installing packages on my computer etc. Perfect for a beginner.

Things like config files, their structure etc was all new to me. For example, while on Hugo’s website, you read that you can use yaml, toml or json format for the config file, I later found out later that yaml is a bit easier to read.

This is just something minor because there are toml to yaml converters online and they are basically text files with slightly different format.

The next step is finding a suitable theme that I can use without too much modification. Having used Wordpress, I know that finding a suitable and easy to modify theme can save a lot of time.

I tried a few themes including Ananke, Mainroad and eventually settled on PaperMod. The next step was modifying the theme to make it look like my old WP site. It is still not there yet but good enough for now. I did not aim to have an exact look from the prior website in WP.

Exporting my articles from Wordpress wasn’t difficult once I found the right tool to do it. I used lonekorean’s script that converts a WordPress export XML file into Markdown file.

Further “processing” of individual articles is required because the exported file from Wordpress do not contain things meta description, canonical url and etc. These are for SEO purposed.

I’m not sure if there is a better faster way to process and clean up the articles though. Perhaps someone with Python skills can write a script to crawl their own site to get the meta information from individual pages and add them to the markdown files automatically.

Anyway, I did it manually for approximately 200 articles. Quite a number. The good thing is that VS Code have a function to “Find and Replace” somethings. Not all things though can be done though.

For examples shortcodes for YouTube embeds which I have a lot on my site. There were some mistakes when I use “Find and Replace” for replacing previous YouTube embeds. This was also partially due to the different ways I’ve embedded YouTube videos in the past.

I have a long list of redirects and also need to create and update the list to make it work in Hugo.

After the migration, I quite happy for what I get.

Steps To Write A New Article In Hugo

To write an article on Hugo now, these are the steps I use:-

  1. Start up VS Code. It is a powerful text editor that can connect & upload files to a repository like Github.
  2. Create a folder with the article name, an image folder and then an index.md file
  3. Copy the frontmatter format from another article. Frontmatter is a way to create metadata in a markdown file plus display options in Hugo.
  4. Write the article. Add video embeds, links etc
  5. Save the article.
  6. Run Hugo on my local computer to generate html files
  7. Sync the file in VS Code to Github.

Github is already synced to Cloudflare where my site is hosted. Linking Github to Cloudflare is done once only.

With Hugo, when I see something that needs fixing like a broken link, I go through all the steps above. Having done it a few times, I find that it gets easier.

Would I do it again

Maybe and maybe not. I learned a lot which will come in useful in the future.

For example frontmatter is used in different static site generators and other sofware as well. Same as VS Code, Github, etc. These are tools and processes that can help me build in the future.

I’m thinking of doing some basic websites in the future and will use a bit of what I’ve learned.

Should you migrate to Hugo?

Wordpress isn’t bad. In fact it is quite powerful and easy to use.

Using markdown to write an article is different and in many situation, Wordpress is easier and simpler.

With Wordpress, you don’t have to remember how to format your articles, links, images etc. You can resize images easily within WP, add a YouTube url and it will automatically look good.

It can also help you check your spelling, your word count etc.

With markdown it is possible to miss a space or character and the embed wouldn’t work. So I keep a Notion file open to copy code I need to use.

Wordpress isn’t perfect either and neither is Hugo. Both have their strengths.

If I can get someone to help manage the server, I might have stuck with Wordpress. However that cost more money than running my own server on Digital Ocean.

All in, I think for me the benefits outweigh the disadvantages of migrating despite the time and work it took. I’m happy for the whole thing.

Summary

It was a good experience and learning process for me. If I were to do another migration, which I might for the second site, I think it will be much faster now having gone through the process once.