Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Shortcode

Since Version 2.5 WordPress supports so called Shortcodes. They have been introduced for creating macros to be used in a post's content. For examples of shortcodes and how to use them, see WordPress.com Shortcodes, though some shortcodes featured there are exclusive to WordPress.com.

A trivial shortcode for a gallery looks like this:

[gallery]

Shortcodes can also be used with additional attributes as the following example shows:

[gallery id="123" size="medium"]

Both examples will display an image gallery, which would be hard to maintain when writing the HTML markup for it and keeping it in sync with uploaded images. By using a shortcode, the markup for the gallery will be created dynamically and automatically.

Built-In and Additional Shortcodes

WordPress does offer some of the shortcodes by default (for example the gallery one) and plugins can add their own as well via the Shortcode API.

The following shortcodes are included with WordPress:

Escaping Shortcodes

Sometimes you may wish to use the text which usually represents a shortcode in your posts. To do this, you need to escape the shortcode by using two sets of brackets instead of just one. So to display this in your post:

[gallery]

You would write this:

[[gallery]]

For shortcodes that have a start and end tag, you only need to escape the very first and very last brackets:

[[shortcode] ... [/shortcode]]

Note that only shortcodes that are currently available can be escaped in this manner. Using double brackets around text that is not currently registered as a shortcode will result in both sets of brackets being displayed in your post, not just one as when escaping registered shortcodes.

Shortcodes in Widgets

By default, WordPress does not support shortcodes within Sidebar Widgets until 4.9. It only expands the shortcodes within the content of a Post, Page, or custom post type. To add shortcode support to sidebar widgets, you can install a plugin, use the below code, or review Widget Improvements in 4.9:

add_filter( 'widget_text', 'shortcode_unautop' );
add_filter( 'widget_text', 'do_shortcode' );

It is important that these lines be added in this order. The first line prevents WordPress from turning line breaks into paragraph tags, since this keeps shortcodes from working. The second line is the one that makes the shortcodes work.

Shortcodes for Missing Plugins (Unregistered Names)

Outside of the built-in shortcodes all others are added through plugins. If the plugin which provides a given shortcode is missing or deactivated WordPress will treat the entire shortcode, its attributes, and the content inside of it as normal plain text and preserve the special characters on the output HTML.

Assuming we have a plugin which renders happy ASCII art…
Input
[happy /]
[happy]Yay![/happy]
[happy direction="left"]<Yay>[/happy]
with plugin
&lt;(^_^)&gt;
&lt;(^_^)&gt; -- Yay!
&lt;(^_^&lt;) -- &lt;Yay&gt;
(rendered) <(^_^)> <(^_^)> -- Yay! <(^_^<) -- <Yay>
without plugin
[happy /]
[happy]Yay![/happy]
[happy direction=&#8221;left&#8221;]<Yay>[/happy]
(rendered) [happy /] [happy]Yay![/happy] [happy direction=”left”][/happy]

Resources

Related

WordPress Shortcodes: [audio], [caption], [embed], [gallery], [playlist], [video]