Converting to Hyde

· Submitted · Read in about 5 min · (970 Words)
tags: · tech ·

I hosted my blog ( via WordPress for several years, with the previous iteration running from 2012-2016. I’ve never been completely happy with WordPress , due to issues with security, functionality, themes, and performance. I read a great post from Katie Zhu about NPR’s static site template and how they were able to serve a popular site with purely static pages on Amazon S3. If NPR could host their site with static pages, my site should be a breeze.

I had done some research into static site generators and other blog alternatives, including GitHub Pages/Jekyll, Octopress, Svbtle, Medium, and others. I made a list of features I wanted and tried to track down the right solution. Steve Losh migrated to the Hyde static site generator and comprehensively detailed the process on his blog. While I was more comfortable with PHP (and evaluated Pelican), I figured that this was a good opportunity to learn some more Python while following Steve’s guide. Much of the styling here comes from his examples.


Steve’s migration to Hyde was six years ago, in 2010. In the time since then, the version of Hyde he used was deprecated (now called hyde-old) as well as the Aardvark Legs CSS suite. In fact, many of the Hyde documentation links you’ll find online either 404 or take you to a Chinese domain squatter. Luckily, Steve forked the version of Hyde he’s using on GitHub, so I was able to use the same code. That’s one of the benefits of a static site generator: as long as they output valid HTML, they’re never obsolete. With WordPress, it was scary to run more than a day or two without updates due to security concerns.

I setup a Python virtualenv for my Hyde site, created a set of folders, and got everything installed. There were some issues with getting the right versions of things installed. This server runs Ubuntu 14.04, and many of the packages were newer than they were when Steve set up his blog, and incompatible with what I was trying to do. I had to set up several of the requirements files with version information to grab the right copies of Django, etc. I set up some bash aliases to make things easier (generating pages, etc).

WP to Hyde

The next step was to convert my old WordPress posts to Markdown for use with Hyde. I used Boris Smus’ fork of exitwp, which he to convert his own blog to Hyde. I decided to jettison all of my old WordPress comments (RIP) as they’re no longer needed. I also punted on trying to convert the WordPress URL format to the Hyde URL format, and just created a very long list of nginx rewrite rules, like the following:

if ($request_uri ~ ^/278/wow/clearing-your-wow-creature-cache-automatically/$) {
        rewrite ^(.*)$ /blog/2013/02/clearing-your-wow-creature-cache-automatically/ permanent;

I manually added Hyde headers to all of the posts, as there were only 33 or so of them.

{% hyde
    title: "Converting to Hyde"
    snip: "Static site generator"
    date: 2016-02-28
    categories: ["tech"]

There was plenty of manual work to convert the stuff exported from exitwp into clean Markdown. I removed all the WordPress “more” buttons, completely rebuilt a bunch of tables from the ground up, and spent at least two hours redoing all of my WoW class colors article in pure HTML.

I did run into one platform issue , where Hyde was generating my articles out of order. When I’d browse the list of articles, the years would be mixed up. I found out that this was an issue due to how Python walks directories on different platforms, and opened a pull request to fix this issue. I would like to thank my friend Justin Cook for finding the fix for me!

I’m using Disqus for comments, FeedBurner for feeds, Google Analytics for stats, and nginx to serve up the data.


The coolest blog feature on my list of requirements was *sidenotes* . Thomas Ptacek uses sidenotes to great effect on his blog. I found Waylan Limberg’s guide to writing Python Markdown Extensions and sampled exaroth’s Custom Span Class Markdown Extension for most of my code. I wrote an extension called SNExtension (for Sidenote Extension) that will automatically place the text between the marker characters into a span with class sidenote which then gets moved over to the right via CSS. I extended it to include the ability to number sidenotes as well as hiding them on small screens, as seen on via the Tufte-Jekyll style.

[>] - start sidenote
00-content - ## is the sidenote_id, followed by a dash, then the content
[/>] - end sidenote

I’ll get this up on GitHub sooner or later.


I spent a long time browsing various fonts on Google Fonts before arriving at Fira Sans as my font of choice. I am also using Audiowide for my titles and headers. One of the cool things about separating content from layout is that I can change fonts globally with a snap of my fingers. I replaced the codehilite Markdown stuff with highlight.js as Boris Smus did as well. I find that it does a better job, especially with Windows shell scripts/batch files.


I also took the opportunity to update my nginx server (via the direct nginx repos) to support HTTP/2 and updated my SSL config. Adding Let’s Encrypt support is coming up shortly, as my certificate from StartSSL expires in May. I also pulled out CloudFlare temporarily, as it wasn’t handling SSL very well. I had hacked in CloudFlare support without actually delegating my DNS to CloudFlare (using an old hosting provider partner of theirs) but it’s time to either move my DNS there or find an alternative solution (like S3).