You write a tutorial that mentions a shortcode in a code example, and the published page shows something else: a gallery, a block of other posts, or an empty gap where the example should be. WordPress ran the shortcode you were only trying to mention.
<code>. The block editor’s Code block protects you, because it saves each [ as [. Inline code inside a paragraph doesn’t, so [gallery] typed as inline code becomes a real gallery on the page. To show a shortcode safely, put it in a Code block, write it with WordPress’s own double-bracket escape, type the opening bracket as [ in the code editor, or name it without brackets. Then check the published page, because an example that runs often leaves nothing visible behind.Table of Contents
The two ways it shows up
The loud version: a theme guide names one of the theme’s page-builder blocks in inline code. That name is also a registered shortcode, so WordPress runs it, and the middle of the step fills with a complete posts block: other articles’ titles, author and category links, and the theme’s generated CSS. The stored text looks fine. On a test page built that way, the rendered HTML started like this:
<code><div class="td_block_wrap td_flex_block_2 tdi_4 td_flex_block" data-td-block-uid="tdi_4">
<style>/* custom css - generated by TagDiv Composer */Code language: HTML, XML (xml)The quiet version: a sentence explains that some rule leaves [caption] and [gallery] alone. Both are shortcodes built into WordPress. They run, have nothing to display, and leave this:
leaves WordPress shortcodes like <code></code> and <code></code> alone.Code language: HTML, XML (xml)The reader sees “like and alone”, and nothing logs an error. A page like that can stay live for days before anyone notices.
An example that runs rarely looks broken. Often it just leaves a gap where the example should be.
Why WordPress runs it
Shortcodes are processed by do_shortcode(), which WordPress applies to the whole post content after the blocks are rendered. It looks for anything in square brackets whose name matches a registered shortcode, and it doesn’t skip <code> or <pre>. To the Shortcode API, text inside a code element is just more content.
That also explains why the problem hides. Only registered names run. In one sweep of seven bracketed examples in inline code, five displayed correctly simply because nothing on that site registered [current_year], [safe_email …], [admin_only], [table id=1 /] or [block …]. Activate a plugin that registers one of those names, a table plugin for instance, and an old tutorial starts rendering a table in the middle of a sentence.
Which code is safe in the block editor
The editor has two ways to mark code, and they behave differently:
- The Code block is safe. When it saves, the Code block replaces every
[with[(and the//in a line that is only a URL with//). Browsers display[as an ordinary bracket, butdo_shortcode()doesn’t see an opening bracket, so nothing runs. You can see this in the Code block’s save function in WordPress’s block library. - Inline code is not. The inline code format, the one you get by typing text between backticks in a paragraph, just wraps the text in
<code>. It escapes nothing, so a shortcode name typed there will run.
If your site uses a syntax-highlighting plugin, check that it keeps the escape too. The Syntax-highlighting Code Block plugin, for example, decodes the code to highlight it, then puts [ back before the page is assembled, so its code blocks stay safe.
The Code block escapes your brackets for you. Inline code in a paragraph leaves them alone.
Four ways to show a shortcode
| Method | Where it works | What readers see | Watch out for |
|---|---|---|---|
| Put it in a Code block | anywhere | the shortcode, as typed | nothing; this is the safe default |
Double brackets, [[ and ]] | paragraphs and inline code | the shortcode with single brackets | only for registered shortcodes; an unregistered name shows both brackets |
Type [ for the opening bracket | the code editor view, or a Custom HTML block | the shortcode, as typed | check it again after any later edit in the visual editor |
| Name it without brackets | anywhere | “the gallery shortcode” | readers lose the exact syntax |
The double-bracket escape is built into WordPress: when it finds a shortcode wrapped in two pairs of brackets, it returns the inner one as plain text instead of running it. Written in a paragraph, this:
Add [[gallery]] to the post to show its attached images.Code language: CSS (css)reaches the reader as “Add to the post…”. Because the escape only applies to names WordPress recognizes, it’s the right choice for core shortcodes like [gallery], [caption] and [embed], and for any plugin’s shortcode that’s active on your site.
If you publish posts by script
Content sent through the REST API, an importer or a markdown converter never passes through the Code block’s save step, so it gets none of that protection. Both failures above are typical of posts created that way. Escape code the way the Code block does, before the content is sent. In Python:
import html
import re
def escape_code(text: str) -> str:
"""Escape code for WordPress post content the way the block editor's Code block does."""
out = html.escape(text, quote=False).replace("[", "[")
return re.sub(r'^(\s*https?:)//([^\s<>"]+\s*)$', r"\1//\2", out, count=1, flags=re.M)
Code language: Python (python)Apply it to inline code and to code blocks. Five samples, run through it:
[gallery] -> [gallery]
[table id=1 /] -> [table id=1 /]
rows[0] < 3 && x -> rows[0] < 3 && x
https://example.com/a -> https://example.com/a
[[caption]] -> [[caption]]Code language: HTML, XML (xml)The last line is the catch: once your script escapes brackets, write shortcode examples with single brackets. A double-bracket example would now display both pairs. With the escape in place, the quiet example above renders as <code>[caption]</code> and <code>[gallery]</code>, which readers see as [caption] and [gallery].
How to check a published page
Because the failure is often silent, check the page itself. Open the page source and search for <code>:
- An empty pair,
<code></code>, where your example should be means a shortcode ran and printed nothing. - A code element that contains
<div,<style>or a<table>means a shortcode ran and printed its output there. - A page with more headings or links than you wrote is the same failure seen from outside. In the theme-guide case above, the page suddenly had 11 subheadings instead of 6, plus links to unrelated posts.
If you publish often, script the first two checks and run them on every page after it goes live, alongside the other render bugs that pass every check.
The short version
- WordPress runs registered shortcodes everywhere in post content, including inside
<code>and<pre>. - The Code block is safe: it saves
[as[. Inline code in a paragraph is not. - To show a shortcode: use a Code block, write it with double brackets (registered shortcodes only), type the bracket as
[in the code editor, or name it in words. - If a script publishes your posts, escape
[in code the way the Code block does, then write examples with single brackets. - Check the published page for empty
<code>elements or code that contains page markup.
Frequently Asked Questions
Why do the double brackets sometimes show up on the page?
WordPress only unwraps double brackets around a shortcode it recognizes. For a name that isn’t registered on your site, the double brackets are left exactly as written. The same happens if your publishing script already escapes brackets in code.
Does the Classic Editor protect shortcode examples?
No. The Classic Editor has no Code block, so it saves your brackets exactly as typed, and a shortcode inside <code> or <pre> runs just as it does in inline code. In the Text tab, type the opening bracket as [, or use double brackets for a registered shortcode. Then check the published page, because switching back to the Visual tab can undo a typed entity.
