Moving from wordpress.com to Jekyll on Netlify

This is a guide that I wish I had. Having decided to migrate from wordpress.com, what steps should I follow move a webiste/blog like mine to Jekyll while preserving things I’ve found useful, such as SEO, canonical Urls, and analytics?

What made me want to switch were the feature of the Chirpy Jekyll theme. All are appealing to me, especially, the table of contents. What made me want to switch from wordpress.com was the costs associated with hosting. Saving on them would allow me to pay for other services I needed.

There are a few things I still wanted (somehow) to retain as I moved, such as:

• maintaining an article’s SEO. I like how the Yoast plugin helps with the SEO descriptions. Could I retain that even without Yoest? Yes, using the excerpt key in the post’s YAML Frontmatter.
• maintaining the Urls of the previous articles. Wordpress generates these in the form https://domain/year/month/day/post-title. I don’t want to (nor can I) edit social media posts where I posted the “old” urls. Nor do I want to tell people that have linked to the articles to update their urls.
• If possible, I’d like to keep the analytics too.

That involved:

• trying out the Chirpy theme to check if my usecase fits;
• exported the WordPress posts and images;
• updating DNS to point to the site of Netlify;
• checking for, and fixing, broken links: before, and after, DNS changes.

Steps followed

Try out Chirpy

I tried out the Chirpy Starter. I was happy to have work the first time. But customising it is limited. Adding fathom analytics (affiliate link) didn’t work for me. So I switched to using the upstream version.

When following the setup guides, pay special attention to _config.yml: the values for url and basedir are crucial, especially when using a custom domain. Without these, tools that check for broken links will report many broken links. An advantage of Netlify is that, even if the url is missing, the website still works. It becomes a problem when using a custom domain.

Export WordPress content to Markdown

Export posts from Wordpress using the excellent WordPress to Jekyll Exporter plugin. All posts, images, and comments are exported as a downloadable zip file.

• This exports all posts in Markdown format. The posts metadata, such as the permalink, date with timezone, author, categories, tags are saved in the the post’s YAML frontmatter
• All images are kept in the wp-content folder.

WordPress content to Jekyll site

From the extracted zip, I copied all files to the Jekyll site. Then adjusted one post at a time in chronological order - starting from the oldest post. I noticed the “recently updated tags” in the Chirpy theme track “recently updated” posts. That means, if I add the posts in reverse chronological order, the “recently udpated tags” would point to the oldest posts.

• As I was doing that, I adjusted the frontmatter. I kept the date, title, permalink. I added the canonical url, and reworked categories and tags. For some posts, I added an excerpt.
• For each post, I updated the paths to the images, accounting for the wp-content folder. And also links to other internal posts.

Check for broken links before DNS changes

After depoying to Netlify, and checking that most things work well, I used https://www.brokenlinkcheck.com/broken-links.php to check for broken links. Some links were definitely broken - these had to be updated. Most of the broken links were false positives because of the way Jekyll and this theme serves them.

Change DNS for custom domain

After a couple of day, I changed the DNS settings in WordPress to point to Netlify. Yes, I still use WordPress and my domain provider. Adjust these according to your domain provider.

• In WordPress (docs)
  • Navigate to Domains -> (domain name) -> DNS Records -> Add a record.
  • Select Type to be A.
  • In “Points To”, populate with the values from the Netlify documentation, https://docs.netlify.com/domains-https/custom-domains/configure-external-dns
• In Netlify
  • Navigate to the site ->Domain Management -> Domains -> Add Domain
  • Point to your domain. In my case, that was juliusgamanyi.com
  • Netlify verifies that I own the domain, generates HTTPS certificates, and the site becomes HTTPS-enabled.

Check for broken links after DNS changes

When I checked for broken links again, there was one that stood out. It was a post that had a space in the title. For titles that have spaces or other characters that must be encoded, ensure that such characters have been replaced with the correct encoded characters. For HTML, that special character would be %20. Otherwise, landing on those pages leads to 404 error page.

Thanks to Barrett Burnworth who pointed out landing on a 404-error page from my pinned tweet.

Endnotes

I’m happy with the site. It’s pleasant to my eyes - both the light and dark modes. Writing in Markdown reduces the reluntance I felt when using the WordPress Editor.