This short (?) post explains how your can escape shortcodes when you don’t want the shortcode to work as a filter, but instead want them to appear literally. This comes in handy in posts wanting to explain how a certain short code is applied.

Summary

Bottom line is that you must be aware of the shortcomings of WordPress when it comes to shortcodes. Many of the issues mentioned above have come to WordPress because shortcodes are interpreted with regular expressions and that’s, unfortunately, a poor-man’s tool for balancing expressions, leading to traps that potentially wreak havoc on your whole page when you attend to them too carelessly.

That said, most general scenario’s will “just work” with one of the two following approaches:

• Doubling the square brackets as in [[gallery]].
• Doubling the outer brackets, as in [[code][/code]].

If these don't work properly, and they might, check whether your scenario fits in one of the six scenario's depicted below:

Six scenario's to consider

There are essentially four scenario's, but I'll show all six I encountered:

1. Escape single shortcodes

You can escape single shortcodes by doubling the square brackets. Suppose you want the user to see:

[gallery href="http://image.com/img.jpg"]

Then type double brackets:

[[gallery href="http://image.com/img.jpg"]]

2. Escape opening / closing shortcodes

You can escape opening / closing shortcodes by doubling only the outermost square brackets. Suppose you want to display this:

[code]
printf "Hello world"
[/code]

Then type this:

[[code]
printf "Hello world"
[/code]]

3. Escape shortcodes inside the TinyMCE graphical editor

The short answer: don't even try, you'll find yourself in quite a fix quite quickly. The long answer: create a shortcode to print shortcodes, for example, you could use Global Content Blocks.

Were you to try it inside TinyMCE, the editor would insert newlines between the extra square brackets, making the rest of the shortcode work normally. If you would use GCB's or a similar technique, TinyMCE cannot attempt to expand the shortcode, because GCB's are placeholders for content defined globally (which is also the downside of this approach: you need to create a global placeholder for something you want to use in only one post).

Alternatively, consider Scripts n Styles, a plugin that allows you to create shortcodes per post. Suppose you add a shortcode using SnS with the name "short" and its contents should come up as [gallery] on your website, then you only need to type the shortcode you just created

[sns_shortcode name="short"]

in your TinyMCE editor and all's fine and dandy. It will just be printed as [gallery].

4. Escape only an opening shortcode of a shortcode pair (without the closing part)

This one proved trickier than I originally anticipated. Especially if your page elsewhere has a closing shortcode listed of the same type (in fact, I managed to wreak havoc on this very page quite often this way). The only way I found to fix it is the "old" way, before escaping shortcodes by doubling the brackets was added to WordPress.

The shortcode [code] always requires a closing shortcode. Suppose you want to display only the opening shortcode, like this:

[code]

Then type this:

[code]

5. Escape shortcodes inside shortcodes, nested shortcodes

Most of the time escaping nested shortcodes "just works". But it highly depends on the shortcode author. I.e., I couldn't get the Acronix Shortcodes to work at all with nested shortcodes.

When I wrote this article, it seemed originally that the [code]-shortcode worked normal with nested and nested escaped shortcodes, but sometimes I noticed the rest of my page totally corrupted by non-closed opening shortcodes. So, in all but a few circumstances, the [code]-shortcode and perhaps others behave as expected.

For example, the code example on (2) above was originally written as:

[code]
[[[code]
printf "Hello world"
[/code]]]
[/code]

But this failed with a later edit of this page, and I assume it's because I had added other [code]-sections prior to it which confused the WordPress filtering. So I changed the code example of (2) with the following:

<pre class="brush: plain">
[[[code]
printf "Hello world"
[/code]]]
</pre>

Moral: nested shortcodes sometimes work, sometimes you'll need to find neater ways and use HTML or one of the escaping tricks of section (6) below.

6. When escaping doesn't solve the issue.

In some code sections above, I used <pre> to make it possible to render the code-sections correctly, because it wasn't interpreted correctly always. But that's a specific workaround that only works when you have a workaround that can be solved with pure HTML.

You can consider the following three work-arounds when normal escaping doesn't work:

• Use an HTML entity, like [ or [;
• Use an invisible and harmless HTML code, like <a name="#"> in the middle of the name of the shortcode (see below);
• Use a zero-width Unicode character, like Zero Width Non Breaking Space, which you can insert with typing&#xFEFF;.

An example of the second point above with the gallery shortcode is:

[galler<a name="#"></a>y]

which will show up on your blog as:

[gallery]

And an example of the third point above with the gallery shortcode is:

[gallery]

which will show up on your blog as:

[gallery]