Using Gists for to Share WordPress Code

When I first started this blog (and actually on other prior blogs), I used various syntax highlighter plugins in order to handle rendering source code.

Though there’s something to be said for the various options that are available, I’ve been using Gists for the last several months. And though they don’t render in RSS readers – something I’ll discuss more in a bit - the more I believe that they are a better alternative than some of the plugins that are available.

Using Gists

For anyone who’s new to the concept of GitHub – or just gists in general – if you have a GitHub account, you’ll find that you also have a place to manage your gists. You can think of these as short code snippets (that may be made up of multiple, small files) to demonstrate how to do something.

They aren’t used for full-on projects, but offer a variety of benefits (and a few disadvantages) as it relates to using them to using Gists for WordPress code in your blog.

Codercat

Oh, and for those of you who are used to using Gists, I still recommend GistBox (this is a free app, so it’s not an affiliate link or anything – I just like sharing good software).

Anyway, enough about all of that. There’s a number of reasons that I that I think using Gists make a suitable alternative to other plugins.

1. Third-Party Hosted

Though I’m someone who generally believes in content ownership, though I also think that there’s something to be said for having certain types of work hosted elsewhere. Then again, just because code isn’t hosted on my site doesn’t mean I don’t have the code saved on a hard drive, does it?

Anyway, having code that’s easy to read, formatted, and embedded in your blog in a third-party service designed specifically around this purpose goes a long way in making it code readable, accessible, and sometimes easier to update after someone conducts a code review.

2. More Feedback

I’ve talked about code reviews a number of times here (and even invite others to critique the code that I share) and how valuable I think they are.

When we opt to to using Gists on our blogs to share code, we’re able to easily have others provide their feedback either in the comments on the blog or comments on the Gist (if you opt to make it public).

3. Easier to Update

On top of that, let’s say that someone offers you a great code review and you get an email about the comment that was just left.

We can update the code shared on our blog without actually having to login to our blogs. Instead, we read the comment in the email, hop into the Gists in another tab (or another browser window if you’re one of those types ;), and then edit the code.

The next time someone reviews the code, the site will pull in the most updated copy of the code.

Not bad, right?

Not Without Shortcomings

Of course, there are some shortcomings of going this route. I mean, what solution doesn’t have it’s own set of fails? :)

Deckfailcat

 

But when we come across these shortcomings, I think it’s important to try to identify them and provide suitable work arounds when possible.

1. No RSS Support.

One of the biggest complaints that I get about using Gists rather than a syntax highlighting plugin is from those who read posts in various RSS readers. In short, the code doesn’t show up.

It’s a pain point, I know, so – until this is something that’s resolved – I try to always provide a link just before I display the Gist so the reader is able to open the code in another tab or window and follow along with the article without too much trouble.

2. Shortcodes and the Like

I’ve shared my thoughts on shortcodes before, so I’m not repeating them here. Though I love oEmbed and think it’s much better than shortcodes are, dropping them in the middle of a post still creates a weird content experience.

Unfortunately, for now, there’s no real alternative:

  • Either you’re going to need to use a plugin that requires shortcodes
  • You’ll need to stick with oEmbed
  • Or you’ll need to avoid sharing code all together

And, naturally, I think the final option shouldn’t even be an option at all :).

On the upside, my arguments against shortcodes are usually related to non-programmer types so it’s not really that much of a problem as it relates to including them in our posts.

Just My Preference

To be clear, this is not to put down any of the existing syntax highlighter plugins – I still use them in some of my old posts as they work great and I’ve no intent to go back and migrate all of that code to GitHub;.

That said, I do think that using Gists to host code provides an exceptional experience for the developer, for the contributors, and mostly for the readers (if it wasn’t for that whole won’t-render-in-RSS-thing ;).

But I also realize that this, like everything else shared here, is subject to feedback.

So if you have an alternative, if you like it, if you hate it, I’m all ears. I still want this to be as accessible and easy to read as much fun as it is to continue to write. It may be a hard sell, but if you’ve got an alternative, I’m listening :).

14 Comments

We have a small plugin for this job, also a simple idea for the feeds. Maybe helpful for other users – https://github.com/inpsyde/Inpsyde-oEmbed-Gist

    Thanks Frank – happy to check this out. I know you and I have talked before about this exact issue. Nice to see a solution of sorts for it :).

Do not forget performance issues!

Regarding the RSS issue, there are few plugins available from the repo to tackle this problem.

    I’d love a list – I know Frank provided one above, but I’m also eager to see what else is available and how they work with other existing plugins, as well.

The number of http requests some of the syntax highlighting plugins make is amazing. With SyntaxHighlighter Evolved, for example, I think I counted 29 once, if I remember right. Just for that reason I think embedding gists is a better solution, even if they don’t look as pretty.

The gist link in the blog is incorrect :)

Hi, thanks for the article. The gist solution seems fine but I prefer not to rely on a third-party service for my snippets. I prefer using custom post types instead so I can manage to update code easily.

Anyway Gist is a great place to share code.

Hey Tom,
Great article.
I didn’t realise that Gists don’t show on an RSS feed. That’s a great take-away from your post.
I need to check our RSS feed more regularly. You just kinda expect it to work all the time.
Cheerz,
Wil.

Leave a Reply

Name and email address are required. Your email address will not be published.

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>