I’m taking my things and moving to Hugo.

I like a great many things about WordPress. It’s easy to set up. There is an overwhelming community behind it, chock full of free themes and plugins. There’s a nifty mobile app. It has a built-in commenting system. Really, for the most part, it’s great. That said, there is one thing about WordPress I’ve never particularly enjoyed. And, unfortunately, it’s something that’s rather essential to, you know, a blogging platform.

The writing experience.

The writing experience on WordPress is not that great. Frankly, I think it sucks. I’ve tried to make it work for me - really, I have - but over the past five years every time I sit down to write a blog post, I somehow always feel like I’m arm wrestling with the WordPress editor. Like, it’s very hard to get into a flooooooow. Instead, I’m continuously irritated, like a mosquito buzzing by my ear. The textbox is too small. The font is way too small. Their attempt at distraction free writing involves panels flying in and out every time you so much as bump your mouse. I’m not always satisfied with the html output of the visual editor, yet I find the text editor too cumbersome to format text as I go. I’d much prefer a MarkDown editor, where formatting text doesn’t interrupt your writing flow. The WordPress Jetpack plugin does indeed support MarkDown formatting, but not in real time. A few weeks ago I found a third party plugin that offers vastly better, real-time MarkDown support. At first I was thrilled. It seemed that good. I thought maybe, just maybe, this will make writing in WordPress pleasurable. But it quickly became apparent that there were some kinks to work out. Kinks which, once again, left me more focused on a distracting user experience rather than on the words I wanted to compose.

The editing experience isn’t any better. After composing your text, the next logical step is to preview it on your site so you can proof the final result. For me, at least, this involves re-reading the entire post and checking for errors, inconsistency, and flow. Inevitably, this results in a back and forth process where I find something to correct, flip back to the editor, make a change, and then refresh the preview page. This cycle is slooooow. Not only because it takes a second or two for WordPress to render the page, but also because every re-rendering causes the page to scroll back to the top. If you happen to be editing a post long enough to necessitate scrolling down to your previous location, this is painfully distracting. Wait, which paragraph was I on again? (…scroll, scroll, scroll…)

When I first started using WordPress five years ago, all this seemed far more tolerable. But in a world where Ghost and Medium exist, with their infinitely superior writing1 experiences, I have to wonder: How has WordPress managed to lag so far behind on this front? I suspect the answer is simply that, today, WordPress is more CMS and less blog that once was the case. I’ve been sitting on the edge of my seat assuming that any day now WordPress will announce an overhaul to the native editor. Whether (and when) that will happen is anyone’s guess, but I’m done waiting. I’m throwing in the towel, despite all the years I’ve invested in learning WordPress and the fact that I really like the current look and feel of my current site. I’ve finally decided that if the platform sucks away my desire to write - the entire reason to have a blog at all - well then, it’s time for me to look at another framework.

But which one? I put together a list of requirements and went from there.

1. MarkDown

I have a mad crush on MarkDown. I love it because it’s so freaking easy to format text as you go without taking your hands off the keyboard. Even adding links is quick and painless.

2. Atom

Atom is my favorite text editor. Just add a few plugins, and you’ve got the perfect long-form markdown text editor. The first, markdown-preview, I think comes prepacked with Atom. It displays a real-time MarkDown preview pane that’s very similar to what Ghost has. The second, markdown-scroll-sync, keeps the prevew pane location synchronized with your cursor’s location in the MarkDown document itself. And finally, zen, is a real distraction-free writing experience. When active, it puts Atom in full-screen mode, hides the tree view panel, and reduces the visible width of your text to a more readable amount. (You also can adjust the width to suit your preferences.) Don’t forget to turn on Typewriter mode, which keeps the current line of text vertically centered!

3. FAST Previews

Seconds add up, and I was pretty tired of all the wasted time waiting for WordPress to refresh my previews and then scrolling back down to my previous position. I wanted a platform that generated previews FAST, FAST, FAST.

4. Themable & Pluggable

Need I say more? Gotta be able to easily customize the look and feel of the site.

5. Thorough Documentation

If there isn’t thorough documentation such that I can quickly and easily get up to speed, then I don’t want any part of it.

6. Free & Open Source

I’ll assume this doesn’t require elaboration. :)

And the winner is…?

There’s a fair bit of excitement surrounding static site generators these days. I kept hearing murmurs of enthusiasm from several of my coworkers because of the significant performance benefits of a static site over a dynamic one. So I think the seed was planted in my mind when I totally inadvertently came across this video called “When NOT to use Drupal” a few weeks ago. The video focuses on Drupal, but could just as easily been talking about WordPress when the presenter discussed the virtues of static sites for certain projects like, say, a blog. I spent the next several hours/days scouring StaticGen, comparing at least a dozen different static site generators. Eventually, I settled on Hugo. So far - I couldn’t be happier.

I know a couple people who dumped WordPress for Hexo and reported being reasonably happy with it. Hexo is based on nodeJS, a technology I’m keenly interested in, but I couldn’t get past Hexo’s less-than-complete documentation. Hugo, on the other hand, met all my criteria and has a reputation for being unbelievably, blazingly fast. It’s written with Go, a language that wasn’t necessarily near the top of my To-Learn list before I started using Hugo - but it most definitely is now.

With Hugo, I can write in Atom with MarkDown and when I press Ctrl + S the preview page reloads so fast it practically brings a tear to my eye. What’s more is that it does not scroll the preview page back to the top! That’s right! The preview page maintains its position during reloads, which vastly improves the editing process both in terms of speed and pleasure.

My New Blogging Workflow

I plan on writing another post that goes into more detail about how I use Hugo, but here’s a high-level overview of my new workflow.

  1. Write Offline

    I now write all my content offline, using Atom, with Hugo running in the background serving up page content as I go. I usually have Atom on my main monitor and a live preview page on my secondary monitor.

  2. Push changes to GitHub

    Once I’m satisfied with a set of changes I’ve made to my site, be it to posts, pages, or anything else, I push the changes to the master branch in the GitHub repository I created specifically for this blog.

  3. Use AppVeyor to build site content and SFTP it to Webfaction

    I have an AppVeyor project that detects changes to my Blog repo, builds out the site content using Hugo, and then immediately pushes the output to my Webfaction account.

What this means is that I can create a git branch for use while I craft a set a changes. Once they’re completed, I push them into master and within a couple of minutes time, those change will be live on this site. It also means I have a complete revision history of every change I’ve ever made to the site, which is fantastic.

Now more than ever before, I feel like I can sit down and get into the zen-flow of writing without the constant friction I felt with WordPress’s editor. It’s nice. Now “all” I have to do is finish porting all the content from my now-legacy site over here. :)


1. So why don't I just use Ghost or Medium? Both have other detracting aspects which are deal breakers for me. Self-hosted Ghost felt very raw and bare-bones, and upgrading it seemed more manual than I was willing to endure. I'm also unwilling to pay a monthly fee to host an account on ghost.org. Medium, on other hand, requires you to [sacrifice a higher degree of ownership](https://medium.com/policy/medium-terms-of-service-9db0094a1e0f#.cqumse9jo) over your work than I am willing to accept.