Migrating from WP Engine to GitHub Pages

After giving it nearly a full calendar year, I have decided to migrate my PHP blog (PHP Avenue) off of WordPress via WP Engine and on to GitHub Pages. The decision ultimately boiled down to WordPress having way more available functionality than I was actually using and me not seeing the value of it as a whole because of it. The blog itself is doing quite well with traffic that has been trending in a hockey stick over the last few months. Unfortunately, my eyes were bigger than my stomach regarding what I would be doing with the site in addition to generating quality content. As the site traffic increases, I will probably revisit things like polls and forums but will do so by utilizing third-party services or simply reinventing the WordPress wheel with my own custom solution.

With all of that being said, I want to discuss the migration steps I took to migrate off of WordPress / WP Engine to GitHub Pages but first I want to sing the praises of WP Engine. Cancelling was a very straight forward process but actually made me feel more like I was breaking up with someone than cancelling a hosting account. What made me feel this way was the first line from their knowledge base article:

We make it easy to leave because it forces us to earn your business every month.

Unfortunately there was no earning my business back, but it wasn’t their fault. Over the last year I had a small number of support requests and each was handled very promptly and never resulted in back and forth due to uneducated support reps misundertanding my request (as I have experienced with other companies that I no longer do business with). The cancellation process was very painless:

  1. Open a support ticket.
  2. Fight off feelings of guilt while composing break up message.
  3. Verify last 4 digits of the billing credit card (per response).
  4. Donezo.

I never had any issues with my blog being hacked and only had a single issue with my blog not upgrading properly with left me with a white page. That was due to my own ignorance and upgraded a plugin that was not verified to work and was easily restored with WP Engine’s backup / restore tools. That’s not counting the time at the beginning when I used a plugin that wasn’t on the approved plugin list. Again, that boiled down to my own ignorance. I will continue to speak very highly of and recommend WP Engine to anyone looking for secure WordPress hosting. The cost is quite justified considering the ease of use of the platform and the piece of mind that they will deal with fixing up your blog if it’s hacked. If you’re interested, here is my obligatory referral link

Enough about my ex and more about this migration process. I opted to manually migrate the posts because I wanted really tight control so I could proof everything to make sure it still looked decent and make any tweaks / correct typos. Migrating the HTML to markdown was accomplished with a pretty incomplete mapping in my .vimrc that would get the HTML nearly converted with the exception of some inconsistencies in my posts. It was easier to correct those manually than try to accommodate the variations. The process took me maybe a couple of hours (70 some off posts) as I had a pretty good copy and paste rhythm down.

With WordPress I was using the SEO Yoast plugin for clean URLs or additional meta data or something like that. I went ahead and hand rolled everything into my default layout. Regarding my layout, I kept everything looking exactly as it did on when it was running on WordPress with the intention of reworking the design in the very near future as it’s been the same thing for the last year and I’m tired of looking at it.

Getting the layout and the content migrated over wasn’t a bad process for the most part. Two things that were issues were syntax highlighting for my code snippets and search capabilities. Syntax highlighting with GitHub Pages just didn’t want to work right for me. I used the fenced code blocks as well as the highlight liquid tag to no avail. I had mixed results by including the <?php delimiter but ultimately didn’t want to have that in every single code sample, especially when it wasn’t necessary. Fortunately I came across highlight.js which I was able to get working without much effort.

Syntax highlighting was a pretty minor inconvenience compared to search. With WordPress search was built in but with GitHub Pages you’re running on jekyll and don’t have a scripting language directly available. Taking the path of least resistance, I went ahead and set up a Google Custom Search engine. It was free and well, I hear these Google guys (and girls) are really good at search, so I figured why the hell not! The search itself works great, the major issue I ran into was attempting to style the search input to match the old style of the site. The search input itself contained multiple elements that would be swapped out when you give it focus. I was able to hack it together but not without some concessions like moving my CSS file to the bottom of the page so the styles override Google’s inline styles. The plan is to completely rework the search along with the rest of the site tweaks, considering hardly anyone uses the search I may even drop it entirely.

The last thing I had to get working were comments. I already use Disqus on this blog and wanted to do the same on there. Disqus is free and doesn’t require any backend scripting so it’s perfect for static sites. On the first go, I went ahead and installed the Disqus WordPress plugin and kicked off an export to Disqus. Seemed like it worked fine but I came to find out that only 5 of my 25 comments were migrated over. Second attempt included a manual dump of my posts from WordPress and a manual import of said dump file. That worked out perfectly as all of my comments made it over with no duplicates! Since I kept the slugs the same when migrating the posts, the content appeared as expected.

As always, the coolest part of these migrations is gaining the ability to blog with vim and manage my blog from the command-line. I’m going to be giving goyo.vim a shot in the near future, as well as some other “zen” writing plugins to help make that experience even better. Using GitHub Pages is also free, while not a major contributing factor, it’s always nice to save a few bucks. OH and now my blogging can be considered Open Source contributions since everything is now living in a public repo

I know that working on your blog from the CLI is not for everyone (but it is hipster as hell ;), but neither is WordPress as I contintually get reminded of. At this point I probably won’t give WordPress another shot, ever. But never say never, am I right?

Josh Sherman - The Man, The Myth, The Avatar

About Josh

Husband. Father. Pug dad. Musician. Founder of Holiday API, Head of Engineering and Emoji Specialist at Mailshake, and author of the best damn Lorem Ipsum Library for PHP.


If you found this article helpful, please consider buying me a coffee.