in Learning, Reflection

I’ve decided to migrate away from WordPress in the new year. I’ve gone back and forth about this and played with several options such as a headless WordPress option.

While I’ll continue to use WordPress at DHF and in some freelance projects, I’ve moved away from it for a few key reasons which I’ll highlight at a later point. For now, I just want to chronicle the steps needed to migrate my content.

Step 1: Media Library

In a previous post, I mentioned that I’ve been transitioning to using Cloudinary for all of my image needs. Cloudinary is a fantastic service and I highly recommend it. I started using their WordPress plugin about 6 months ago and gradually integrated it into my workflow. However, I still have several images uploaded to the WordPress media library that I need to migrate.

I grabbed all the remaining photos from my /wp-content/uploads folder via SFTP. If you need a quick, effective tutorial on this process, check this out:

Step 2: Upload to Cloudinary

WordPress automatically sets several photo sizes for each source image uploaded to the media library. I only need to re-upload the source image and not the 4+ variations that I downloaded from my /wp-content/uploads folder.

I logged in to my Cloudinary account and began uploading through their UI. For those unfamiliar with their service, you upload your source images to Cloudinary and then you can use their URL based API to do things such as resize, compress, and filter your source images. It’s a fantastic service!

Step 2b: Adding Alt Text to Cloudinary Images

Once my images were uploaded into Cloudinary I had to reset all the alt text for them since I did this in the WP media library. This is a tedious process but will only need to be done once since everything uploaded to Cloudinary from this point forward will have them. I also am on the fence about whether I should add alt text through Cloudinary’s library or if I should do it manually on my sites, but for now, I’m going to just replace all the image alt text in Cloudinary’s library.

Step 2c: Tweaking Images in Cloudinary

This was a pretty solid opportunity to play with Cloudinary’s fantastic set of transformations and to start understanding how the API works. Each transformation that you perform on the images in their dashboard is stored in the image URL that you then fetch from their server. This is incredibly powerful since you’re able to “chain” transformations together and have it all encoded in the URL that you request.

I’m still barely scratching the surface with what Cloudinary is able to do. Currently I’m focused on transferring my WordPress images, but I know that there is so much more that I can do.

Step 3: Exporting Content

Typically this process would involve doing an export of all my WordPress content from the dashboard, but when I initially set up my site I also installed WordPress GitHub Sync. I configured the plugin to push content updates to a repository upon each publish/edit. Each post is stored in the repo as Markdown, including categories, tags, and permalinks. Featured images aren’t stored because of how (I’m assuming) they’re handled in WordPress.

Since I have this repo of content I’ll have this as a safety hatch. I’m also looking into having some migration tools (WordPress to Jekyll) and this WordPress to Gatsby plugin to handle some of the heavy lifting. I like knowing that my WordPress content is saved to a repository incase anything happens during the migration.

Step 4: Handling URL Structure

One big question I have is how to handle my permalinks. Currently, my links are constructed on WordPress as /category/post-name. If I wanted to maintain continuity (and not have to create redirects) I could use this structure since I have each post category in the frontmatter. However, I’m aware that this is also a time to rethink my URL structure. Marty passed this on to me: Indieweb article on URL design. If I change my URL structure I’d likely need to either do some edits on linked content, add some redirects, or just bite the bullet and start fresh on some linked content. I’m still undecided on this decision, but I see the merits in switching to the structure outlined in the linked Indieweb article.

Step ???: New Site Architecture

The process of grabbing my content outlined in the previous steps was pretty smooth other than the URL structure decision. Next, I need to make some big choices about how to architect my site. I’ve decided that I’m going to use GatsbyJS, but the bigger question is whether or not to use a CMS as my content backend. Throughout the past year I’ve been rather intrigued by headless CMSes and the JAMStack. I’ve now created two projects using this approach and I see the merits. However, I’m not sure that my site will have enough content needs to justify using a CMS. This is a rather big reason for moving away from WordPress as the content management system.

I’m currently considering something a bit more API driven such as Contentful or just using MDX. I’ve always loved writing in Markdown and MDX levels up the experience substantially by allowing the creation and integration of JSX components. This is essentially similar to WordPress shortcodes and is extremely potent for content creation.

I’ve toyed around with some basic layouts and I think I’m getting closer to what I want to do. I have some Figma mockups from over the summer that I want to revisit. As usual, I begin by creating mockups in Figma and then recreating in HTML/CSS before moving into JSX/Styled Components. I know that this is likely an unnecessary middle step but I like the process of building something out step-by-step along the way. It helps me make sure that I’m writing clear and (hopefully) semantic HTML before I create JSX components. I think that this process has helped me build out my HTML/CSS skills this past year and I enjoy writing HTML/CSS.

Wrapping Up

I’m now much closer to migrating! There are still some key points I need to decide, but I’m able to maintain motivation and excitement by jumping back and forth between working on layout and site architecture (and migration). I hope to accomplish this by the new year, but may be slightly late!

Once I migrate I’ll create a companion post reflecting and reviewing on the process, and hopefully providing any insights that I gleaned along the way.

Let me know what you think