Shortcodes Should Never Be Included With Themes. Period.

ThemeForest recently updated their WordPress theme submission requirements to be more stringent and more inline with WordPress theme development best practices.

The guidelines require the use several of WordPress’ core features, standard theme hooks, and disallow PHP functions (like base64 and fopen) that really shouldn’t have ever had any place in a WordPress theme to begin with.

Basically, pretty much WordPress.org’s Theme Review policy, give or take a few things.

Overall, it’s a step in the right direction and moves to promote best practices on one of the most popular WordPress theme marketplaces on the net. There’s just one problem…

Admissible Shortcodes

One thing that particularly caught my eye, however, was how certain “admissible” shortcode functionality was allowed (i.e. by directly including them through the theme’s functions.php file). The ones listed as “admissible” included the following:

  • buttons
  • pricing tables
  • image containers
  • dropcaps
  • lists

Inadmissible shortcodes include: maps, accordions and toggles, boxed contents, column, contact forms, charts.

The Problem with Shortcodes in Themes

I can’t really put it better than Justin Tadlock already has. One of the most noticeable issues, is that when a user changes themes, the shortcodes will no longer be parsed.

Let’s say “Super Awesome” theme had a shortcode feature that would output a big green button with a link when you typed out something like [button url="http://example.com"]Big Green Button[/button].

Big Green Button

When you switch to another theme (let’s face it, people get bored of themes easily), there’s no more big green button. Instead, you see the unparsed shortcode in the post as if it were any other piece of content, like this:

[button url=”http://example.com”]Big Green Button[/button]

It looks ugly, confusing, and out-of-place, and it’s a pain for the user to go back and remove/replace all of them.

The Other Problem with Shortcodes in Themes

Something that Tadlock went over in his “Dealing with shortcode madness” article is, a lot of shortcodes are so simple and HTML-like, it might even be best to instruct users to write out a little (*gasp*) real HTML code.

The same [button url="http://example.com"]Button Text[/button] shortcode in my example above could be easily rewritten as something like:

<a href="http://example.com" class="button">Button text here</a>

While there may not be CSS code styling the .button selector in a new theme, at least a normal link will show up. Which is a big improvement over an unparsed [button] shortcode showing up in a post’s content.

Plus, I believe every WordPress user should have at least some basic understanding of HTML code. By teaching them, even in little bits (like how to construct a link), will help. If they can understand a shortcode, it won’t take much more to get them to understand basic HTML.

But The Users Don’t Care!

A common argument I see defending all sorts of bad practices when it comes to theme development is that the users simply don’t care. I mean, maybe they never want to update their theme, in which case, this shortcode issue would be a moot point.

The problem is, some users inevitably will want to switch themes some day. Some users will want to install a plugin that might conflict with some other poorly-thought-out code in a theme.

Then, they probably will care, and probably will wonder if the theme they bought with 100s of built-in shortcodes and other superfluous features was really worth it.

The Right Way to Include Shortcodes

Put it in a plugin. A really simple plugin. It doesn’t need a separate options panel. Just literally copy and paste whatever you were going to include via your theme’s functions.php file, and put it in a plugin instead.

It could even be bundled with something like TGM Plugin Activation to make it required on theme activation. Or not. A theme is still a theme without shortcodes.

This way, if the user changes themes, the shortcodes will still work, because that functionality is handled by the plugin that is still active.

Maybe the plugin could also enqueue styles for the shortcodes as well. This way, the big green buttons you included with the [button] shortcode will still be big green buttons, regardless of the theme used.

Why Did ThemeForest Allow “Admissible” Shortcodes?

It’s hard to say what exactly the reasoning behind this decision was. Japh Thomson, a WordPress evangelist at Envato (ThemeForest’s parent company) had this to say about it in a comment on WPMU.org:

Complex shortcode functionality really should reside in a plugin, not a theme. It also just makes sense when you consider most of our authors have multiple themes.

Obviously, he gets it. So it’s a mystery to me why there would be any “admissible” shortcodes at all. And yes, I realize he used the word “complex” in the quote above, and the admissible shortcodes do tend to be pretty simple ones (dropcaps, lists, etc.).

Simple as a shortcode may be, the problems I outlined above will still exist. ThemeForest has shown to be responsive to community feedback, so it’s possible this rule is amended in the future.


I realize this post seems a bit nit-picky, and these new guidelines are definitely a huge step in the right direction. But there’s really no reason any shortcode should be allowed in a theme, simple or not.

Spoiler alert: Didn’t get any responses to that tweet with a real example of a shortcode absolutely needing to be included in a publicly-released theme.

That’s because it’s just not user-friendly for a user to go back and replace hundreds of button shortcodes after they switched to a theme that doesn’t have the exact same shortcode support.

Comments  Leave a Reply

  1. Thanks so much for this post, I have just purchased a ThemeForest theme and I am having this same problem! When we uploaded theme, the pages say the shortcode is not compatible … what to do now to make it compatible? Thanks!

  2. While I agree shortcodes should reside within a plugin instead of a theme, the unparsed code will still appear when the plugin is disabled or replaced by another shortcode plugin. Either way it can be a hassle for the person performing the changeover.

    Learning basic HTML seems best.

  3. Ihor Vorotnov July 28, 2013 at 2:17 pm

    Totally agree on this. Themes should handle layout and styles. Anything that adds some extra features must go in a plugin.

  4. Mathew Porter July 27, 2013 at 6:35 am

    I have the same stance on shortcodes, but can see the reasoning for some themes including them for non tech savy users to add features easily and in turn helps sell more of developers themes.

  5. here here.

    It would also be nice if there was some sort of elegant degradation for shortcodes that are no longer active.

  6. Jens Kilgenstein July 22, 2013 at 8:32 am

    Thus, possible problems can be avoided with functions which may be added in the future in different theme. Issues of maintenance are important purchasing arguments – at least for me!

  7. I completely agree with you. Very few people stick with one theme forever, unless it’s completely custom (and then you don’t have the themeforest problem) and shortcodes are a pain to deal with. I recently discovered this problem when I started changing from a theme-junkie theme to a studiopress/genesis theme. Now I’ve put the change on hold, despite spending $80 on it already, because there is too much to change even on my new site.

  8. Hey Leland, great post, thanks for your thoughts!

    We’ll be releasing an update to these requirements shortly, based on feedback from our authors, and I hope you’ll be pleased with some of the adjustments we’ve made (specifically in relation to shortcodes) 🙂

  9. Andrés Vilarreal July 14, 2013 at 10:39 am

    I think it’s not only a compatibility issue with other themes, but a content-related issue too. A shortcode should be just a helper to process content, and themes should only display pre-processed content, not process the content by themselves. When themes process shortcodes on their own, they’re treating that piece of text (or at least it looks like the developer does it) as a call to a visual element, not to a functional one (what it really is), like if the scope of what a theme is for was missing there. That practice shows a lack of clarity about what content, functionality and visualization are, and how those elements should be managed (i.e., content should be stored into DB, functionality should be managed via WP core and plugins, and visualization via themes; just as a very basic example). There’s no need to be a content expert, an experienced programmer or a great designer to know such things, just a little bit of attention and careful thought on what we’re offering to our users, and how easy or difficult will be for them to use our products. I think it’s OK if you don’t know the differences but you’re open to learn and improve, but, on the other hand, to know and have in mind all these things and offer shortcodes (and any other functionality-related stuff) in themes anyway, that seems to me like a disloyal practice that makes your users captives of your product. I know that sometimes the line between visualization and functionality is really thin, but in most cases the difference is non-discussable.

    Shorry for the long reply, this is a topic that I’m really interested in. Great post 🙂

    1. Hey Andrés, no need to apologize for the lengthy reply, you make some great points!

  10. Thanks for this… I have ongoing issues with shortcodes in themes that I have bought. And when I retheme them, I have legacy code everwhere which needs replacing.

    1. Peter, that’s a perfect example of the problem with shortcode in themes.

      It gets even worse when other non-presentational functionality is also included in a theme, maybe something to talk about in a future post.

Add a Comment

We're glad you have chosen to leave a comment. Please keep in mind that all comments are moderated according to our privacy policy, and all links are nofollow. Do NOT use keywords in the name field. Let's have a personal and meaningful conversation.

WordPress Launch Checklist

The Ultimate WordPress Launch Checklist

We've compiled all the essential checklist items for your next WordPress website launch into one handy ebook.
Yes, Send Me the Free eBook!