Documenting shortcodes is a common task for WordPress plugin developers. You can either use the html entities “[” for “[“and ] for “]”, or use double brackets “[[” and “]]” to escape the shortcode:
Using the html entities would require going into the Text (HTML) mode of the editor, so using the double bracket method would be easier. That is until you attempt to put actions into your shortcodes…
My shortcode function would enque a script when it is called. Today, I noticed some blog pages on the site loading the script, even when the shortcode should not be running. That happened not just on the blog page itself, but on the post list as well. Apparently with the double bracket method, the PHP function for the shortcode is still called, but the output returned from the function is ignored.
I would not expect this behavior if the shortcode is supposed to be escaped… perhaps this is a bug that will be fixed in future versions of WordPress. For me, I’m documenting my shortcodes using html entities from now on, instead of double brackets. You’ve been warned!