Melissa Du,
Back

I tried to use WordPress with Github Pages and it was a nightmare

Recently I migrated this website over to WordPress.org. I tried to set it up so I could use my WordPress site with Github Pages. This post details the tribulations I faced while doing so. Here are the different sections; feel free to skip around however you like:

The backstory

Prior to WordPress, I had a nice set up with Jekyll (static site generator) and Github/Github Pages (hosting & serving). I liked this old setup because it was simple and free. I also liked Jekyll’s plain, minimal look. Jekyll’s visual style is very barebones and that’s exactly what I wanted.

My old workflow for editing and publishing posts was simple. I’d open a text editor, write a post in Markdown, and build and run my website locally to test the changes. Next, I’d push the new post to Github, where I’d re-deploy my website with the changes.

I first started to get annoyed with this setup when I had to re-remind myself how Jekyll glued together and rendered my site each time I wanted to publish a post. I got even more annoyed when I wanted to make changes to the layout. For example, I tried and failed multiple times to add a <meta> tag to the head of my index.html file. This theoretically should have been a very simple change.

If this happened once or twice, I’d be fine with it. The bigger problem is that the purpose of my website is to encourage me to write more. I started to procrastinate writing because there was always some small thing I wanted to fix with Jekyll first. Then, when I made time to tinker around with Jekyll, I was annoyed that I spent more time doing that than actually writing.

Requirements for a new solution

So, I decided to make it was time to change my setup. My new setup had to fulfill just two requirements:

  1. Easy content management. I really like the idea of just writing something, editing it, and then hitting a button to publish it once it’s ready. I didn’t like diving into Ruby files just to fix configuration issues, deploy issues, UI issues, etc. (what was happening with Jekyll).
  2. Be a writing first experience. I’ve never quite liked writing in text editors. Something about it just doesn’t feel right, though I can’t put my finger on exactly what.

I decided to go with WordPress because it seemed like it fulfilled both of those requirements really well. Also WordPress.org is free, unlike Webflow and Ghost, two alternatives I considered that are both quite pricey ($20/month for Webflow and $29/month for Ghost) and loaded with a bunch of features I don’t need yet.

Two big initial mistakes

As mentioned above, previously I used Github/Github Pages to host and serve my website. Github was free and worked great, so I wanted to rig up my WordPress setup to also use Github and Github Pages.

The only requirement to use Github Pages is that your site has to be static. Some light Googling showed me that there were a few plugins that converted WordPress site files to static pages. There were even a few tutorials describing how to do this, so I was confident this would be possible. That was my first big mistake.

Next, I began figuring out how to get WordPress to run locally. That was my second big mistake. My logic here was simple. Previously with Jekyll, I’d run my website locally, add my changes, and then push the new version of my website to Github to redeploy it. Thus, if I wanted to use WordPress with Github and Github Pages, then I should run my WordPress site locally, add my changes, and then push the new version of the site to Github.

While this logic wasn’t bad, I really should have tested the core assumption that it relied on first (the fact that the WordPress site could be converted into a static website). Or I should have done a bit more research than just some “light Googling” before venturing into a solution and stubbornly refusing to give up.

A warning (because hindsight is 20/20)

Here’s what I know now: running WordPress locally is a nightmare. Successfully figuring it out was way harder than it should have been. If you’re trying to do this yourself, don’t. You most likely don’t need to, and there’s probably another solution you can use to get to what you want.

(I should also caveat that I know almost nothing about Apache, MySQL, FTP, and PHP. If you’re familiar with them, then you might not have the same issues. However, I really don’t think I should have needed to learn about all of those technologies just to set up WordPress locally.)

The treacherous journey to run WordPress locally

First, I downloaded WordPress.org and installed it locally. The official WordPress installation page implied that I also needed some combination of Apache, MySQL, and PHP. A few of the links on that page were broken, a red flag that I promptly ignored.

I read a few other tutorials and subsequently downloaded and installed XAMPP, making sure to include Apache, MySQL, PHP, and phpMyAdmin in the installation. I opened up XAMPP and pressed the “Start Application” button. That took me to an error page.

I clicked through some XAMPP tabs and pressed a few more buttons that started Apache, MySQL, and ProFTD. Now pressing “Start Application” took me to an XAMPP page. This seemed promising, but I still got an error page when trying to access my WordPress site which should have been running locally.

I bopped around a bit more and figured out that I had to enable local forwarding in XAMPP on an available port. I roll my eyes and question why XAMPP is so difficult to use.

Now that I could see my WordPress site locally, I still couldn’t do anything (e.g. create post). I learned that I needed to create a database locally via phpMyAdmin. Again, this is something that should have been easy, but the interface SUCKED. I had such difficulty performing such a simple action. I mean…just look at it:

php myAdmin home page phpMyAdmin home screen

Looking at this screenshot now makes me annoyed all over again.

More annoying issues I faced

I then ran into some issues that took me a long time to figure out. Surprisingly, there was not a lot of advice out there on good solutions. I spent more time than I’d like to admit on WordPress support forums and arcane blogs. I’ll include the two most annoying issues here for posterity and in the event that another poor soul is also sifting through Google searching for a solution.

Annoying error #1: “to perform the requested action WordPress needs to access your web server”

To fix this, add define( 'FS_METHOD', 'direct' ); to your wp-config.php file.

Annoying error #2: fix the file and folder permissions error in WordPress / “installation failed could not create directory”

To fix this, you need to give XAMPP write access to the local directory you have WordPress set up in. I spent awhile messing around with quite a few config files (like .htaccess) and FTP permission codes to no avail. The solution was ultimately simple: right-click on your local WordPress directory, click “Get Info”, scroll to “Sharing & Permissions”, and change the permissions on your directory to “Read and Write (anyone)”.

Finally, it’s working?

At long last, all of this is finally working and I now have WordPress running locally.

Anyways, the next step is to install a plugin to convert my site into a bunch of static pages. I go with SimplyStatic, the most popular and highly recommended plugin to do this.

I immediately run into quite a few errors with SimplyStatic. After progressively resolving each one, I ultimately run into one I can’t fix. I search some more and realize that it’s because SimplyStatic was only compatible with an earlier version of WordPress than the one I was running. I dig further and realize that the plugin hasn’t been updated for over two years. And there don’t seem to be any currently updated plugins that do this conversion. Epic FAIL.

I didn’t want to sink in even more time to learn how to convert the WordPress PHP files into static pages. I decided to cut my losses right there and abandon ship.

The Conclusion

TL;DR? Don’t try to run WordPress locally, and don’t try to use WordPress with Github Pages to host and serve it. It won’t work.

I ultimately ended up going with Siteground for managed hosting. Siteground’s interface is awful, but after poking around a bit I got most of it set up. I had a few minor configuration issues when enabling HTTPS and spent ~30 minutes chatting with a customer support agent, who was actually quite helpful.

Postscript: I’m never satisfied and here are a few more things about WordPress that I’m annoyed with

Unless you want your WordPress site to look bad or just like everyone else’s, you’ll probably want to customize an existing theme to your own liking. To do this, you’ll still need to hack around with code (in this case, a combination of HTML, CSS and PHP). Theoretically, you could probably install a plugin to help you do this, but that’d probably slow down your site and further obscure how things actually work.

Getting used to WordPress itself was a bit of a curve. The main dashboard, for instance, is completely useless to me. I’ve just been ignoring all parts of the interface I don’t need, which thus far has been working pretty well. If you liked this post, add your email address below to stay updated whenever there’s a new one. Or you can follow me on Twitter. I like talking to people there.

© Melissa Du.RSS