nahnu_code_block_build_block_markup()

nahnu_code_block_build_block_markup() is how another plugin or theme generates this plugin’s blocks programmatically, as block-comment markup ready to insert into a post’s post_content. It’s the method WP Super Docs’ own OpenAPI sync is built on, and it’s available to any plugin doing the same kind of thing: parse some structured source (an OpenAPI spec, a different API description format, anything else), and turn it into real, editable blocks instead of a fixed template.

Detecting that the plugin is active#

if ( class_exists( 'Nahnu_Code_Block' ) ) {
    // Safe to call the methods below.
}

Block registration happens on the init hook, so if your own code runs earlier than that, wait for init (or a later hook) before calling nahnu_code_block_build_block_markup(). It looks up the block’s registered schema, which doesn’t exist yet before init fires.

Calling it#

$markup = Nahnu_Code_Block::instance()->nahnu_code_block_build_block_markup(
    'endpoint', // short slug, no 'nahnu-code-block/' prefix
    array(
        'method'  => 'POST',
        'path'    => '/v1/customers',
        'summary' => 'Create a customer.',
    )
);

This returns a ready-to-use block-comment string (<!-- wp:nahnu-code-block/endpoint {...} /-->), suitable for appending into a post’s post_content before calling wp_insert_post() or wp_update_post(). It uses WordPress’s own serialize_block() internally, so the output is byte-for-byte what the block editor itself would produce.

Any attribute you don’t pass falls back to that block’s own registered default, from its block.json, so you only need to specify what actually varies for your use case. Pass an empty array to get a block with pure defaults.

If the slug isn’t one of this plugin’s blocks, you get a WP_Error back instead of a string, so check with is_wp_error() before using the result. The valid slugs are: code-block, endpoint, parameters, request-response, response-body, status-codes, error-codes, events, servers, auth, try-it, api-navigation.

Building a full endpoint page#

Blocks are independent. There’s no special nesting required, so concatenate several calls to build a whole section:

$blocks = Nahnu_Code_Block::instance();

$content  = $blocks->nahnu_code_block_build_block_markup( 'endpoint', array(
    'method'  => 'POST',
    'path'    => '/v1/customers',
    'summary' => 'Create a customer.',
) );

$content .= $blocks->nahnu_code_block_build_block_markup( 'parameters', array(
    'parameters' => array(
        array( 'name' => 'email', 'type' => 'string', 'location' => 'body', 'required' => true, 'description' => 'Customer email address.' ),
        array( 'name' => 'name', 'type' => 'string', 'location' => 'body', 'required' => false, 'description' => 'Customer full name.' ),
    ),
) );

$content .= $blocks->nahnu_code_block_build_block_markup( 'response-body', array(
    'returns'   => 'Returns the created Customer object.',
    'responses' => array(
        array( 'status' => '200', 'contentType' => 'application/json', 'body' => wp_json_encode( array( 'id' => 'cus_123' ), JSON_PRETTY_PRINT ) ),
    ),
) );

wp_insert_post( array(
    'post_type'    => 'your_docs_post_type',
    'post_status'  => 'draft',
    'post_title'   => 'Create a customer',
    'post_content' => $content,
) );

$blocks = Nahnu_Code_Block::instance();

$content  = $blocks->nahnu_code_block_build_block_markup( 'endpoint', array(
    'method'  => 'POST',
    'path'    => '/v1/customers',
    'summary' => 'Create a customer.',
) );

$content .= $blocks->nahnu_code_block_build_block_markup( 'parameters', array(
    'parameters' => array(
        array( 'name' => 'email', 'type' => 'string', 'location' => 'body', 'required' => true, 'description' => 'Customer email address.' ),
        array( 'name' => 'name', 'type' => 'string', 'location' => 'body', 'required' => false, 'description' => 'Customer full name.' ),
    ),
) );

$content .= $blocks->nahnu_code_block_build_block_markup( 'response-body', array(
    'returns'   => 'Returns the created Customer object.',
    'responses' => array(
        array( 'status' => '200', 'contentType' => 'application/json', 'body' => wp_json_encode( array( 'id' => 'cus_123' ), JSON_PRETTY_PRINT ) ),
    ),
) );

wp_insert_post( array(
    'post_type'    => 'your_docs_post_type',
    'post_status'  => 'draft',
    'post_title'   => 'Create a customer',
    'post_content' => $content,
) );

Landing generated content as a draft rather than publishing directly is worth doing regardless of what you’re importing from. Auto-generated documentation is a starting point a person should review, not a finished page.

Related: rendering without post_content#

nahnu_code_block_build_block_markup() is for when you want block markup inside post_content, which is the right choice if you’re generating draft posts or pages. If you’re rendering somewhere that isn’t post_content at all (a template, a widget, a page-builder module), the plugin has a more direct pair of functions, available since version 1.0.2.

nahnu_code_block_render( $slug, $attrs ) returns the block’s rendered HTML as a string, and nahnu_code_block_the( $slug, $attrs ) echoes it directly. Both take the same slug and attributes array as nahnu_code_block_build_block_markup(), but skip block markup and post_content entirely:

if ( function_exists( 'nahnu_code_block_the' ) ) {
    nahnu_code_block_the( 'endpoint', array(
        'method'  => 'GET',
        'path'    => '/v1/customers/{id}',
        'summary' => 'Retrieve a customer.',
    ) );
}

Like the block-markup builder, these can’t be called before the init hook, since they look up the same registered block schema. If you call one outside WordPress’s normal head-enqueue timing (for example, from inside a shortcode or a late template part), the plugin prints its stylesheet late rather than skipping it, so the block still looks right. Both also accept a third argument: an associative array of CSS custom property overrides (--nahnu-code-block-bg, -chrome-bg, -fg, -border, -muted, -accent, -accent-fg) scoped to that one call, for matching a specific template’s colors without touching the plugin’s global theme settings.

If what you’re building is a full OpenAPI importer rather than a one-off insert, look at the Nahnu_Code_Block_Openapi class. It’s the same converter this plugin uses internally for its own OpenAPI sync, covered in the How the sync works and What gets generated docs, and it’s built to be called from your own code: hand it one resolved operation object and it returns ready block markup, the same shape nahnu_code_block_build_block_markup() produces for a single block.

Tips#

• Land generated content as a draft, not a published post. Whatever you’re importing from, an automated conversion is a starting point a person should review, not a finished page.
• Build one block’s attributes array, check it against that block’s real attribute list (see the block registry in each individual block doc), and test it before writing a loop that generates hundreds of posts from it. A typo in an attribute name fails silently: the block just falls back to its default for that field.
• Pass arrays and objects as real PHP arrays, not JSON strings. nahnu_code_block_build_block_markup() handles the JSON encoding into the block comment itself.
• Missing attributes aren’t errors. Any attribute you leave out falls back to that block’s block.json default, so you can build a minimal call first and layer in optional fields only where you have real data.
• Check for WP_Error after every call. An unknown slug is the most common cause. Since the valid slugs are fixed, this usually means a typo rather than something you need to handle per import.
• Call this no earlier than init. If you’re running from a cron job, an admin-ajax handler, or a CLI script (WP-CLI, a custom import command), make sure WordPress has already fired init before your code runs.