Common Issues

This is a first-stop checklist for the problems people run into most, most of which turn out to be expected behavior rather than a bug once you know the cause. If your issue is specifically about a shortcode attribute not doing what you expected, see Shortcode attribute gotchas instead. If a block is rendering but showing the wrong content, empty fields, or stale data, see Block not showing expected data.

“I can’t find the block in the inserter”#

Search for “Nahnu” in the block inserter (the + button), not the individual block name. All 12 blocks, the code block and the 11 API-documentation blocks, are grouped under that search.

If you’re on the Classic Editor rather than the block editor, this is expected: none of these blocks can be added through the Classic Editor’s own UI, since that editor doesn’t support blocks at all. You have two options that don’t require switching editors:

• Place any block with the shortcode, which works in Classic Editor content, widgets, and anywhere else shortcodes are processed.
• If you’re a developer working in a theme template, widget, or page-builder module, call nahnu_code_block_render() or nahnu_code_block_the() directly from PHP. See the doc on building your own importer.

Also confirm the plugin is actually active under Plugins, and that your WordPress version meets the plugin’s minimum (6.3 or later, PHP 7.4 or later, per the plugin’s own readme). A very old WordPress or PHP version can prevent the plugin from loading at all, which would explain the blocks being completely absent rather than just hard to find.

“A block renders, but with no styling”#

This is usually a load-order issue rather than a missing file. A few things to check:

• You’re on a version older than 1.0.2, and the block was rendered from nahnu_code_block_render() / nahnu_code_block_the() or the shortcode, from a template or widget that runs after wp_head() has already printed (a common situation, since template code usually runs after get_header()). This exact case was fixed in 1.0.2: the plugin now force-prints its stylesheets when a block renders late. Updating the plugin resolves it.
• A caching or optimization plugin is stripping or deferring inline styles. Some “optimize CSS delivery” or “remove unused CSS” features can strip styles they don’t recognize as used, since they analyze the page before a dynamically rendered block adds its markup. Exclude the nahnu-code-block-style and nahnu-code-block-api-style handles from that plugin’s optimization if it offers an exclusion list.
• A third-party script injected its own UI into the block’s <pre> element and its CSS is colliding with this plugin’s own. Some themes and plugins scan the page for <pre><code> and add their own copy button or language label to anything they find; if that happens inside a Nahnu Code Block, both sets of UI can visually stack. The nahnu_code_block_pre_attributes filter exists specifically so that other plugin can be told to skip elements it shouldn’t touch. See Hooks & filters.

“Dark mode doesn’t match the rest of my site”#

By default, a Nahnu Code Block only follows the visitor’s OS-level light/dark preference. It has no way to know about your theme’s own dark-mode toggle unless you tell it. Register your theme or plugin’s dark-mode selector with the nahnu_code_block_dark_mode_selectors filter:

add_filter( 'nahnu_code_block_dark_mode_selectors', function ( $selectors ) {
    $selectors[] = 'body.my-theme-dark-mode';
    return $selectors;
} );

Once that’s in place, no JavaScript is needed, the block switches instantly whenever that class or attribute changes, since it’s checked via a real CSS selector rather than being read once on page load.

One exception: if WP Super Docs is active, this is already handled automatically, its own theme attribute and color palette are detected and mapped with no configuration needed. Adding your own filter on top of that is usually unnecessary and can conflict with it.

For the full set of theming options, including rebranding the actual colors rather than just switching between light and dark, see Theming & dark mode.

“Try It Console requests fail or get blocked”#

This is very often expected behavior, not a plugin bug. The Try It block performs a genuine request from the visitor’s own browser directly to whatever URL is configured, it never proxies the call through your WordPress server. That means it’s subject to the same rules any browser-side request is:

• CORS. If the API being tested doesn’t send Access-Control-Allow-Origin headers permitting your documentation site’s origin, the visitor’s browser will block the response, and they’ll see a network error in their own console, not something this plugin can catch or work around. This has to be fixed on the API server’s side, not the documentation site’s.
• Mixed content. A request from an https:// documentation page to an http:// API endpoint will be blocked by the browser. Serve the API over HTTPS, or expect visitors to see it fail.
• Auth headers visible to the visitor. Since the request comes from the visitor’s own browser, anything typed into the Try It Console’s headers or body, including an API key, is visible to that visitor and travels from their machine. Never put a real, working credential into a block’s default header or body values; use a placeholder and let visitors supply their own key.

If requests are failing for reasons other than these, check the browser’s own developer console on the page (not a server error log) for the actual network error, since that’s where the real cause will show up.

“My OpenAPI spec isn’t generating blocks / isn’t updating”#

This plugin itself doesn’t parse OpenAPI specs, resolve $ref pointers, or decide when a sync runs. It’s purely a conversion layer: it takes one already-resolved operation and turns it into block markup. Parsing the spec and triggering the sync, whether that’s a button, a schedule, or something else, is entirely WP Super Docs’ responsibility.

If content isn’t appearing or updating the way you expect, that’s a WP Super Docs question rather than a Nahnu Code Block one. See How the sync works for what this plugin does and doesn’t do, and check WP Super Docs’ own documentation for how and when it triggers a sync.

If blocks are being generated but the content itself looks wrong, missing fields, wrong defaults, that’s more likely covered by Block not showing expected data or Resilience & fallback behavior, both of which explain what happens when the source data is missing or malformed.

General tips#

• Turn on WP_DEBUG while diagnosing. Several failure paths in this plugin (an unresolved shortcode block slug, invalid JSON in a shortcode’s content) render silently in production but print an explanatory HTML comment in the page source when WP_DEBUG is true.
• Check the plugin version before assuming something is broken. A number of the issues above (styling on late-rendered blocks, shortcode attributes being silently dropped) were real bugs fixed in 1.0.2. Update first, then re-test.
• Confirm the plugin is actually active and your WordPress/PHP versions meet the minimums (WordPress 6.3+, PHP 7.4+) before digging further into a specific block’s behavior.
• When something looks wrong only on the front end and not in the block editor preview (or the reverse), that’s a strong signal the issue is in rendering or caching rather than in the block’s stored attributes, which narrows where to look next.