Shortcode Attribute Gotchas

The nahnu_code_block shortcode’s attributes go through WordPress’s own shortcode parser before this plugin ever sees them, and that parser has a few sharp edges that don’t error out. Instead, they silently truncate or corrupt the value, so the shortcode looks like it worked but the block renders with the wrong data, or with stray text leaking onto the page. This doc walks through each one and how to avoid it. For problems that aren’t specific to the shortcode, see Common Issues.

A note on the examples below: every one is written with real, single brackets, ready to copy and paste as-is. If you’re placing an example like this on a live documentation page yourself, don’t type it as plain preformatted text. Use this plugin’s own Code Block block, with Language set to WordPress Shortcode. That block now displays square brackets safely by default, for every language, with no escaping needed from you: a browser still shows real brackets and the Copy button still copies the exact, working text, but WordPress’s own shortcode parser never sees a literal bracket in the page’s HTML to misfire on. Turn on that block’s Show a live rendered preview option if you also want to show the example’s genuine output, which is exactly how the broken examples later in this doc can be shown safely alongside their fixed versions.

Single-quote truncation#

WordPress lets you write a shortcode attribute’s value in three ways: double-quoted (method="GET"), single-quoted (method='GET'), or unquoted for a value with no spaces (method=GET). The parser has no idea what an apostrophe is versus a closing quote, it just scans for the very next matching quote character. If you wrap a value in single quotes and that value contains an apostrophe, anywhere in it, the value ends right there, at the apostrophe, not at the end of your text.

This is easy to hit by accident, since apostrophes show up constantly in ordinary English:

[nahnu_code_block block="endpoint" method="GET" path="/v1/me" summary='Retrieve a customer's own profile']

The summary value silently truncates to Retrieve a customer. Everything after that apostrophe, s own profile'], is no longer inside a recognized attribute. Depending on what follows, that leftover text either gets dropped, gets misread as more (garbled) attributes, or, if it happens to contain its own ], can end the entire shortcode tag early the same way a JSON array’s bracket does (see the next section). Either way, nothing errors. The block just renders with the wrong summary and no indication why.

The fix is simple: always use double quotes for shortcode attributes in this plugin, never single quotes..

[nahnu_code_block block="endpoint" method="GET" path="/v1/me" summary="Retrieve a customer's own profile"]

Double quotes only end at a literal " character, which almost never shows up in ordinary text the way an apostrophe does. If a value genuinely needs to contain both an apostrophe and a straight double quote, there’s no safe way to quote it as a shortcode attribute at all; rephrase the text to avoid the double quote, or call nahnu_code_block_render() / nahnu_code_block_the() from PHP instead, which passes the value straight through with no parsing of this kind.

JSON arrays can’t go in a quoted attribute at all#

The same underlying issue shows up in a more severe form with any attribute whose value is a JSON array or object (Parameters, Response Body, Status Codes, Error Codes, Events, Servers, Request/Response, Endpoint’s related operations, and the code block’s code attribute). WordPress’s shortcode parser scans for the tag’s closing ] using a plain character class with no notion of “inside quotes” at all, so a literal ] anywhere in the tag, including deep inside a quoted attribute’s value, ends the whole shortcode right there. A JSON array always contains at least one ], even an empty one, so quoting it, in either single or double quotes, reliably corrupts the shortcode.

The fix here isn’t better quoting, it’s not quoting at all: these attributes are read from the shortcode’s enclosed content instead.

[nahnu_code_block block="parameters"]
[{"name":"id","type":"string","location":"path","required":true}]
[/nahnu_code_block]

This is covered in full, including the complete list of which attribute is content-based per block, in the Code Block and Parameters docs. It’s included here as a reminder because it’s the shortcode gotcha most likely to be confused with the single-quote issue above, they produce similar-looking broken output, but the JSON one has no quoting fix at all.

camelCase attribute names#

WordPress lowercases every shortcode attribute name before any callback, including this plugin’s, ever sees it. Written as operationId="createCustomer", authRequired="true", or any other camelCase attribute name, WordPress hands the plugin operationid and authrequired instead, with no way to tell that was ever anything but lowercase.

You don’t need to work around this. The plugin looks up each block’s real declared attribute names from its block.json and remaps the lowercased key back to the correct casing before rendering, so operationId="createCustomer" works exactly as written. This is mentioned here only so that if you ever see this plugin’s source or a support thread reference an all-lowercase attribute name, that’s WordPress’s own transport format showing through, not a different attribute or a typo you need to fix in your own shortcode.

Content mangled by WordPress’s own formatting filters#

When a shortcode’s enclosed content lives inside a post’s post_content and gets processed through the_content, two of WordPress’s own formatting filters usually run over it before this plugin’s shortcode callback ever sees it:

• wpautop wraps the content in <p> tags and turns single line breaks into <br> tags.
• wptexturize swaps straight quotes and dashes for “smart” typographic versions, a straight " becomes a curly “ or ”.

Both quietly corrupt content meant to be read literally. wpautop‘s added markup breaks real code formatting, and wptexturize‘s smart quotes break JSON outright, since JSON requires a literal straight " and a curly one isn’t valid JSON syntax. A parameters block whose content looked like valid JSON in the editor can fail to decode on the front end because of this.

The plugin runs a best-effort cleanup pass on shortcode content that reverses the common cases of both filters before parsing it. This catches most real-world content, but it’s a best-effort reversal, not a guarantee, for anything unusual it doesn’t catch (heavily nested markup, an edge case in the quote substitution), the more reliable option is to skip shortcode content entirely: call nahnu_code_block_render() or nahnu_code_block_the() from PHP with the attribute set directly. That bypasses the_content‘s filters altogether, since the value never passes through them in the first place.

Tips#

• Always use double quotes for shortcode attributes, and never single quotes, as a blanket habit rather than something to remember case by case. It costs nothing when the value has no apostrophe, and it’s the only thing that protects you when it does.
• If a value must contain both an apostrophe and a straight double quote, don’t try to escape your way out of it in the shortcode. Rephrase the text, or move that one value to PHP via nahnu_code_block_render().
• When a shortcode-placed block looks subtly wrong, a truncated summary, a missing trailing sentence, a JSON array that silently fell back to empty, check the rendered page’s HTML source for stray text sitting outside the block’s own markup. That leftover text is usually the missing piece, confirming a quoting issue rather than a data problem.
• Turn on WP_DEBUG when a JSON content attribute isn’t decoding. The plugin prints an HTML comment naming which block and attribute failed, and why, rather than failing silently.
• If you’re generating shortcodes programmatically (from a script, an import, user input), build them with a proper shortcode-attribute encoder rather than string concatenation, so quoting is handled correctly regardless of what characters end up in the value.