Migrate from Wordpress to Gatsby and Netlify

After many years I have migrated my Wordpress to Gatsby and Netlify. This short article is a sum up of the main steps how to migrate all the existing articles (and images) and what tools I used. Therefor I moved away from Wordpress to Gatsby and Netlify.

Overview

I migrated my Wordpress blog to Gatsby and at the same time also switching to Netlify. Why? See some of the reasons for this movement

• Like to document everything via AsciiDoc or MD => Gatsby supports MD (AsciiDoc too)
• Simplified management of the articles => Every post is an own sub folder with images and the article as MD file
• Traceability => due the fact everything is in git is the history of changes clear visible
• Better security and less effort to maintain => Gatsby generates the files and produces static content, this reduce the risk enormously.
• Better maintenance (again as own point) => with the latest version of Wordpress has already been improved, but still a lot of effort to keep the plugins up to date, verify if everything is still working etc. Yes, with Gatsby you have also the maintenance task...let's see how much effort this will be.
• Speed => static generated sites are always faster

The steps to migrate the existing Wordpress to Gatsby are as follows

• Export all articles including images from Wordpress, using the existing XML export functionality
• Convert the XML export into Markdown using this wordpress-export-to-markdown
• I adapted the logic in this way to support my syntax highlight markup logic
• Generated a new advanced gatsby project based on material UI, using gatsby-material-starter
• Move the markdown files into the content directory
• ...gatsby develop and enjoy the new site/blog
• ...start optimizing the content files, especially the meta data

The main effort however comes now...the design. Here you can realize yourself, choose different themes, adjust colors etc. I have made following changes to the gatsby-material-starter project

• add table of content support using the gatsby-remark-table-of-contents plugin
• introduce the possibility to define and use a default cover which will be displayed if no cover is defined in a post meta data

Some words to the repository structure: I separated the main site logic, which holds all the gatsby logic from the blog content itself. The relation is done by git submodule. This allows better maintenance regarding versioning, security and re-usability.

Netlify configuration

The integration in Netlify is straight forward. Connect your repositories with Netlify and trigger a build.

Only for the git submodule support is some extra configuration needed. Handling git submodules with Netlify is possible, for this is it mandatory to grant some extra permissions, especially if the repo is private. Details are in the docu.

To sum the steps in Netlify

• Go to Site settings > Build & deploy > Continuous deployment
• Scroll down to Deploy key area: select Generate public key.
• grab the public key

In GitHub

• Select your repository
• then the Settings > Deploy keys: and press Add deploy key
• define a Title and paste the public key from above
• Write access is not needed

Be aware

• that you use SSH to reference the git submodule and not HTTPS

To configure your (sub) domain to reach the Netlify website create a CNAME in your DNS and link to the Netlify generated site.

Summary

The first impressions are based on some up and downs. Up because, the migration started very smoothly. But after the integration in Gatsby I recognized that some of the generated (meta) data are not optimal. So some adjustments and manual efforts are needed. But overall manageable.

The next rock bottom was the general task regarding design. But this is not because of the use technology stack, but rather with me - UI & Co is not my world ;-)

Nevertheless I was very happy to see the first time the following output

...
4:51:29 PM: (build.command completed in 1m 19.9s)
4:51:29 PM: ​
4:51:29 PM: ┌─────────────────────────────┐
4:51:29 PM: │   Netlify Build Complete    │
4:51:29 PM: └─────────────────────────────┘
4:51:29 PM: ​
4:51:29 PM: (Netlify Build completed in 1m 20s)
...
4:51:58 PM: Site is live ✨
4:52:32 PM: Finished processing build request in 4m10.453475163s

I am happy to announce, my blog is migrated. Happy blogging - Blog.

References

• Blog

References

• gatsby-material-starter
• wordpress-export-to-markdown