WordPress shortcodes are a simple way to add styling or other customizations inside of the content of a post, page, or custom post type. They make it very easy to do so, are the way that WordPress does galleries by default, are a great way to execute buttons (I’ve added one we use all over this site at right), and can make adding standard layout code to a post much easier.

Simplest possible shortcode

The anatomy of a shortcode is a shockingly simple thing. Every use of a shortcode must have three things: a left square bracket, the name of the shortcode, and a right square bracket.

[my_shortcode]

So that right there, is a qualifying shortcode (goes by the unlikely name of “my_shortcode”). If there were a plugin running that had registered with WordPress that it transformed the my_shortcode shortcode, you would see its output right there.

Wading in a little deeper

Now that’s not the only way shortcodes can work, so lets cover some of the finer points. Some shortcodes take inputs that determine their output. One way that this can work is that you might use shortcodes to provide a wrapper to common call-out that you use on your site. It is entirely possible, for example that you’d use a shortcode to call out pullquotes (those pretty big quotes from articles that break up the layout to keep a page looking interesting) on your site. In that case, the shortcode might look something like this:

[my_pullquote]This is the inside of my pullquote.[/mypullquote]

Especially if you’re familiar with HTML, XML, or other similar markup languages, this will immediately look familiar, as it bears a striking resemblance to the convention you use to wrap things in HTML. Some shortcodes can work this way. When they do, you call the part the shortcode enclose the “contents” of the shortcode.

Another thing you might want to use to determine the output of the shortcode are “parameters”, “attributes”, or “arguments” that you might want it to use. If you’ve ever seen a WordPress gallery on the “Text” view of your post, you may recognize this syntax:

[_gallery ids="1653,1538,1403,1303"]

Before we proceed: the underscore is not typically present in a WordPress gallery shortcode. But one annoying side effect of how easy shortcodes are to use is that they’re a little hard to demonstrate specifically within WordPress — the magic happens by default — so I had to add the _ to prevent WordPress from swapping it out of the actual gallery it wants to display.

What’s happening here is that we’re giving the gallery an attribute, which is a list of all the IDs (numeric identifiers for) all the pictures that we want it to contain. The shortcode just works in the background as the page is put together to do the magic of making all of that into valid HTML which your web browser can understand and display the gallery that you’re trying to create.

A Dusting of Magic

Shortcodes are a bit like magic. They’re easy ways that you can incorporate complex designs or functionality into a post with minimal typing and freedom from the complexities that you don’t need your posts to contain like a bunch of complex and specific HTML markup.

I strongly prefer to use shortcodes being provided from plugins to those that might be packaged with your theme. I talked quite a bit about it in this post about all the things themes shouldn’t do. The summary is that then you may end up with drab and broken-looking shortcodes when you change themes if you depend on theme-specific shortcodes. It’s not end of the world, but it’s a headache you can and should easily avoid.

I’ve never had cause to use it, but I think this “WordPress Shortcodes” plugin looks pretty neat. You can also browse the WordPress.org Plugin repository with the shortcode tag. Almost anything you need has likely been done before, so you can probably find something that’ll meet your needs for a shortcode. And if not, I’ll have a post in the next few weeks about how you can make your own shortcode plugin.