Dr. Jekyll and Mr. Haack

Dec 2, 2013 blogging jekyll suggest edit

The older I get, the less I want to worry about hosting my own website. Perhaps this is the real reason for the rise of cloud hosting. All of us old fogeys became too lazy to manage our own infrastructure.

For example, a while back my blog went down and as I frantically tried to fix it, I received this helpful piece of advice from Zach Holman.

@haacked the ops team gets paged when http://zachholman.com is down. You still have a lot to learn, buddy.

Indeed. Always be learning.

What Zach refers to is the fact that his blog is hosted as a GitHub Pages repository. So when his blog goes down (ostensibly because GitHub Pages is down), the amazing superheroes of the GitHub operations team jumps into action to save the day. These folks are amazing. Why not benefit from their expertise?

So I did.

One of the beautiful things about GitHub Pages is that it supports Jekyll, a simple blog aware static site generator.

If you can see this blog post, then the transition of my blog over to Jekyll is complete and (mostly) successful. The GitHub repository for this blog is located at https://github.com/haacked/haacked.com. Let me know if you find any issues. Or better yet, click that edit button and send me a pull request!

Screen grab from the 1931 movie Dr. Jekyll and Mr. Hide public domain

There are two main approaches you can take with Jekyll. In one approach, you can use something like Octopress to generate your site locally and then deploy the locally generated output to a gh-pages branch. Octopress has a nice set of themes (my new design is based off of the Greyshade theme) and plugins you can take advantage of with this approach. The downside of that approach is you can’t publish a blog post solely through GitHub.com the website.

Another approach is to use raw Jekyll with GitHub pages and let GitHub Pages generate your site when your content changes. The downside of this approach is that for security reasons, you have a very limited set of Jekyll plugins at your disposal. Even so, there’s quite a lot you can do. My blog is using this approach.

This allows me to create and edit blog posts directly from the web interface. For example, every blog post has an “edit” link. If you click on that, it’ll fork my blog and take you to an edit page for that blog post. So if you’re a kind soul, you could fix a typo and send me a pull request and I can update my blog simply by clicking the Merge button.

Local Jekyll

Even with this latter approach, I found it useful to have Jekyll running locally on my Windows machine in order to test things out. I just followed the helpful instructions on this GitHub Help page. If you are on Windows, you will inevitably run into some weird UTF Encoding issue. The solution is fortunately very easy.

Migrating from Subtext

Previously, I hosted my blog using Subtext, a database driven ASP.NET application. In migrating to Jekyll, I decided to go all out and convert all of my existing blog posts into Markdown. I wrote a hackish ugly console application, Subtext Jekyll Exporter, to grab all the blog post records from my existing blog database.

The app then shells out to Pandoc to convert the HTML for each post into Markdown. This isn’t super fast, but it’s a one time only operation.

If you have a blog stored in a database, you can probably modify the Subtext Jekyll Exporter to create the markdown post files for your Jekyll blog. I apologize for the ugliness of the code, but I have no plans to maintain it as it’s done its job for me.

The Future of Subtext

It’s with heavy heart that I admit publicly what everyone has known for a while. Subtext is done. None of the main contributors, myself included, have made a commit in a long while.

I don’t say dead because the source code is available on GitHub under a permissive open source license. So anyone can take the code and continue to work on it if necessary. But the truth is, there are much better blog engines out there.

I started Subtext with high hopes eight years ago. Despite a valiant effort to tame the code, what I learned in that time was that I should have started from scratch.

I was heavily influenced by this blog post from Joel Spolksy, Things You Should Never Do.

Well, yes. They did. They did it by making the single worst strategic mistake that any software company can make:

They decided to rewrite the code from scratch.

Perhaps it is a strategic mistake for a software company, but I’m not so sure the same rules apply to an open source project done in your spare time.

So much time and effort was sacrificed at the altar of backwards compatibility as we moved mountains to make the migration from previous versions to next continue to work while trying to refactor as much as possible. All that time dealing with the past was time not spent on innovative new features. I was proud of the engineering we did to make migrations work as well as they did, but I’m sad I never got to implement some of the big ideas I had.

Despite the crap ton of hours I put into it, so much so that it strained my relationship at times, I don’t regret the experience at all. Working on Subtext opened so many doors for me and sparked many lifelong friendships.

So long Subtext. I’ll miss that little submarine.

Found a typo or mistake in the post? suggest edit

Comments

33 responses

Oli • December 3rd, 2013
Your "Edit" link for this post is:

https://github.com/Haacked/...

...but I got a 404. THIS link appears to do what you said it would do:

https://github.com/Haacked/...

(notice "gh-pages" and one less "_posts"?)

Cheers,
- Oli
haacked • December 3rd, 2013
Thanks! I forgot to change it after I was done testing!
Mike H • December 3rd, 2013
I used Jekyll for a few years, but the number one complaint I have is that if you have a LOT of blog posts (e.g. 1000) it takes forever for Jekyll to generate the site. I have almost 10 years of blog posts (started in 2004 with .Text and moved to Subtext as soon as it was released) and nearly 1000 unique posts. Jekyll simply isn't viable because of the site build time. The next best option is to render older content as a separate, static "archive" site and only publish new content in Jekyll. However, I notice you migrated all of your content from as early as 2004. How many posts do you have? Are you noticing any performance issues?

Also, when including images in your posts, you cannot use github to upload them, correct? In other words, you're forced to use a local git repo to add images. Running and maintaining the Jekyll/Ruby environment on Windows was always a giant headache. I'd like to be able to go 100% github.com, but adding images to posts would prevent that.

Curious to know your thoughts.
haacked • December 3rd, 2013
I have 1840 posts. GitHub is constantly improving it's infrastructure so it may be faster now than it was in the past.

Running Jekyll is a little slow on my machine, but now that I have it set up, I just do a lot of my blogging in the browser.

> Also, when including images in your posts, you cannot use github to upload them, correct? In other words, you're forced to use a local git repo to add images.

So what I do is create and edit my posts in the browser (https://github.com/blog/132.... The editor lets you drag and drop images and they're hosted on GitHub's CDN.
haacked • December 3rd, 2013
It's now fixed. Were you planning to submit a pull request? :)
Mike h • December 3rd, 2013
I'm not seeing how you can drag and drop images. Click New File icon -> start typing in github editor -> drag an image in -> browser navigates to local copy of image instead of embedding it in the post. I'm using Chrome. Anything special I need to enable or do? Does it have to be a markdown file? Does it have to be on a gh-pages branch (I just tested it on a test repo on master)?
haacked • December 3rd, 2013
Ah, I was mistaken. I cheat a bit. I edit (or create) an issue and drag it into there and copy the resulting markdown into my post. It's probably an abuse of GitHub issues.
Rob Conery • December 3rd, 2013
Good stuff - I love Jekyll :). One thing you might want to do as well is disable the Disqus spam (I think it's called "Discovery?").

Blog looks great :)
haacked • December 3rd, 2013
I kind of liked it because it showed other interesting posts to look at. But it does make it busy.
Travis Illig • December 3rd, 2013
I've actually been considering this exact approach. The only thing I haven't really figured out is how to nicely handle the redirect from old URLs (/archive/blah/something.aspx) to the new ones without extensions (/archive/blah/something/). I've seen some meta redirect stuff combined with JavaScript but... UGH.

How did you handle redirects?
Travis Illig • December 3rd, 2013
It appears that somehow you get "...blah.aspx" to redirect to "...blah.aspx/" and Jekyll just doesn't care. Is that Jekyll magic or something you had to do?
bill • December 3rd, 2013
Hey Phil,

Your "Burning Man" link is broken.
Andy Abbott • December 3rd, 2013
It looks like some of your page URLs didn't transfer correctly.

- Google: https://haacked.com/archive/...
- Actual: https://haacked.com/archive/...

My guess would be a timezone issue with your export script or Jekyll.
haacked • December 3rd, 2013
Good catch! Thanks!
Minnesota Steve • December 3rd, 2013
I think Spolsky's argument is misunderstood.

Let's say HaackedSoftware was a company with Subtext as a product. Time goes by, and many of your customers start realizing that there is other stuff out there that operates in a different manner that makes some tasks a lot easier. And you're looking and thinking to make Subtext work that way would be a substantial amount of work.... a complete rewrite.

Going back to Spolsky's argument... as a company is it wise to rewrite Subtext? The issue you raise of backwards compatibility is really the core of that question. How much effort would be involved to rewrite Subtext in a way that maintains consistency with existing installations and makes everybody happy by providing exactly the same functionality? That's a lot of work, which is Spolsky's point, and by abandoning the existing version as you rewrite you are abandoning the market.

But as a company, what's your main motivation? You want to win over new customers, right? So leave the existing customers on the old system, and start working on a new system, that provides these new benefits that people are starting to notice from other competitive products and over time work towards adding additional functionality that will win over your existing customer base. For those existing customers where the new system meets their needs, they'll use it instead. For those that don't, take their feedback on why the new system won't work and see if it can be improved over time with enhanced functionality. As time goes on the new system should be more on par with the old system and more of your customers will adopt it.

This is sort of what Fog Creek did with Trello. It's something new that does some of what their old FogBugz did, but not everything and it certainly allows teams to work differently in a way that would have been very difficult to introduce to FogBugz.
Guest • December 3rd, 2013
Those were some great times we had. Subtext also opened many doors for me - including you hiring me based on my OSS contributions! Here's a picture of the "core team," and you and I hacking on some Subtext stuff at your house.

Thanks, Phil!
Steven Harman • December 3rd, 2013
Ahh, those were some great times. Subtext also opened many doors for me - including you hiring me based on my OSS contributions!

In remembrance, a picture of the "core team" and another of you and I hacking on some Subtext code at your house.

Thanks, buddy!
Steven Harman • December 3rd, 2013
And somehow the pictures were uploaded twice. Computers... how do they work?
haacked • December 3rd, 2013
Time to create Subisqus! :P

Steve, it was a pleasure working with you back in the day. What are you up to these days? You still blogging?
Scott Stocker • December 4th, 2013
I have never been able to get Jekyll to run locally on a Windows machine. I take it things have gotten better recently?
haacked • December 4th, 2013
Runs fine for me so I assume they have gotten better. :)
Judah Gabriel Himango • December 4th, 2013
The "eight years ago" link (https://haacked.com/archive/... is broken.
haacked • December 4th, 2013
Thanks! I'm pushing a fix now.
DalSoft • December 5th, 2013
If there is anyone interested in static site generation using Razor - I wrote a simple console app to do exactly that. I'm adding a simple markdown feature at the moment.
https://github.com/DalSoft/...
S Krupa Shankar • December 6th, 2013
Subtext- the first 'mixed mode' (classic ASP.NET plus ASP.NET MVC) app scenario I came across - was very useful for me in a particular case with a "legacy" enterprise app.
Bud Parr • December 6th, 2013
Hey, Mike - There's work on Jekyll toward incremental regeneration, which I think will speed things up. There's also an editor called prose.io that I believe (haven't tried it yet) allows you to upload an image.
Steven Harman • December 12th, 2013
It was a grand time working with you as well. I still hold out hope that one day we'll get to work together again, building something great, and having great fun doing so!

These days I spend my days leading backend/web dev at Big Nerd Ranch - so lots of Ruby and JavaScript, though I'm getting into Go as well. And I'm hacking on a side project, http://brewdega.com when I can, while occasionally blogging (http://stevenharman.net).

Hope to see you soon, pal!
parameterz • December 14th, 2013
What about tags and categories?

I really dig the workflow for creating/editing pages, and pull requests, etc using the gh-pages model. It's clearly much easier for you, the author.

But considering that tags and categories are now pointless... it's now much more difficult for the reader. I wonder what your thoughts are on this matter.
haacked • December 14th, 2013
Working on it!
Damien Guard • January 6th, 2014
Enjoyed using Subtext for a while to run my blog too. Was glad to know (and eventually meet over the years) the cool bunch of developers behind it.
spiky • October 13th, 2014
I've been wanting to move from Blogger to Github Pages for a while now. One thing that concerns me is comments. How has been experience with Disqus?
haacked • October 13th, 2014
So far it's been very good. They allow import and export so I feel relatively safe in the choice.
Bogdan Marian • May 22nd, 2018
Running Jekyll on Windows can be easily done using Docker - see https://github.com/BretFish.... This is how I test that my post will look great when hosted on GiHub Pages!