Bloggers: Stop Outsourcing Your Code Samples!

I get it, really, I do. Syntax highlighting plugins can sometimes be a pain in the rear... sometimes they don't work the way you want them to, sometimes they conflict with other things your site is trying to do, and sometimes you have to fight with (some of) them to get the characters you want to display displayed (e.g. encoding greater-than and less-than symbols as > and < instead of just writing > and <)...

Lately I've seen many blogs switching to the use of embedded Gists as a way to show code samples. I think this is a terrible idea.

Sure, Github seems pretty stable and popular now. I love Github and I host many of my projects there, but you won't see me outsourcing my blog code-sample hosting to them.

What happens if they get bought by AOL for two billion dollars and AOL decides they just don't like the Gist service. Poof. Gone. Your blog, which will live on in perpetuity (as long as you keep paying the bills) now has large and important chunks missing. The value of those posts just disappeared.

Even if they decided to give you 6 months notice before shutting the service down? You'd then have to go through your entire blog history and convert the gists into either another service or embed them in the blog directly.

By hosting your code samples elsewhere -- anywhere other than on your own blog -- you're making a bet. And that's not a bet I would make, ever.

I've tried most of the options available. ColdFish, embedded in most versions of BlogCFC is not horrible. I even used the aptly but unimaginatively named Syntax Highlighter.

These days I've settled on what I think is a much more robust solution: Prettify. It's a JS library from Google that is 100% language agnostic. You don't have to do any "brushes" like Syntax Highlighter. You just wrap every code sample in <pre class="prettyprint"> and include the JS library on your page. And if you're not a huge fan of the color scheme, there are existing themes and it's easy to tweak it and create your own, too.

So please, bloggers... Knock it off. You're making the internet worse, not better, with these shenanigans.

Published 2012-04-19 08:18 in 8 Responses Meta

8 responses:

Sam Farmer

2012-04-19 @ 9:35 AM

I agree.

Rob Brooks-Bilson

2012-04-19 @ 1:38 PM

I'm with you on this. Same for presentation slides. Embedding with a service is ok as long as you also provide a link to download the slides *from your site*.

Jim Priest

2012-04-19 @ 2:52 PM

Good post. Even if you use a local solution I'd be careful. I recently moved my blog from WordPress to Octopress. During the transition I noticed a lot of my older posts had code missing. Initially I thought it was an issue with the conversion process but it turns out that over the years, as I had changed syntax highlighting plugins, somewhere along the lines something ate my code. :(

At some point I'll go back and see if I can resurrect the old posts but even if you are using a local solution - it would pay to go back and occasionally check your old posts to make sure the content is still correct, or better yet implement some kind of regular blog backup...

Matthew Reinbold

2012-04-20 @ 3:04 PM

Neat, although I still need to go angle bracket replacement with amperstand-greater-than, less-than, manually entering line breaks, and simulating indentation. Are there macros that could automate this for me? This seems to solve the syntax highlighting but the tedious code-prep work still exists if you're putting code into a pre or code tag, correct?

Matthew Reinbold

2012-04-20 @ 4:08 PM

Hmmmm... adding the 'linenums' class to the block not only adds line numbers, but has the added benefit of zebra striping and handling tabs and newline characters correctly. However, one still has to do & gt; and & lt; angle bracket replacement.

Adam

2012-04-23 @ 1:50 PM

Matthew, are you sure that the character replacement necessity isn't coming from your blog's WYSIWYG editor? I use markdown to write my blog entries, and that means that to include a code-block I simply indent by either 1 tab or 4 spaces. But I paste my code in exactly as in the editor (so using > and < signs, not escaped), and don't have any problems. I'm not sure whether or not my markdown display plugin is encoding them or not, though.

Matthew Reinbold

2012-04-23 @ 2:41 PM

@Adam,

I'm not using a blog editor. Just writing html pages for a presentation.

One of the biggest helps was using the default <pre> tag rather than the more syntactically correct <code> tag. While the code tag is supposed to work I found that much of the preservation of tabs and newline characters was lost. I did, however, still need to manually replace the angle brackets.