How to Interleave Editable Blocks Inside the Custom HTML Block in WordPress 7.1

The Evolution of Hybrid Layouts in WordPress

For years, WordPress developers faced a stark choice when building custom layouts: write raw HTML in a Custom HTML block, or build a fully custom block using React and the Block API. The former gave developers complete control over markup but left clients with a fragile, code-only editing experience. The latter provided a polished user interface but required a build step, JavaScript compilation, and ongoing maintenance.

WordPress 7.1 bridges this gap by introducing support for interleaving static HTML with regular, editable blocks inside the core Custom HTML block (core/html). This hybrid approach allows developers to wrap standard blocks in arbitrary, complex HTML structures. In the editor, the surrounding HTML remains inert and protected, while the nested blocks remain fully interactive and editable in place.

How Interleaved Blocks Work Under the Hood

The core mechanism relies on nesting standard block serialization comments within the boundaries of a Custom HTML block. When the block parser encounters these nested comments, it instantiates the inner blocks rather than treating them as plain text.

Consider the following markup structure:

<!-- wp:html -->
<div class="banner">
  <h1>Static heading</h1>
  <!-- wp:paragraph -->
  <p>Editable paragraph</p>
  <!-- /wp:paragraph -->
  <footer>Static footer</footer>
</div>
<!-- /wp:html -->

When this markup is loaded into the WordPress 7.1 editor, the parser processes the outer <div class="banner"> and <footer> elements as inert, read-only HTML. However, the nested <!-- wp:paragraph --> block is parsed as a live, editable Gutenberg Paragraph block. This allows content creators to edit the paragraph text visually without any risk of accidentally breaking the surrounding HTML layout.

The Block Locking Mechanism

To preserve the integrity of the developer’s layout, WordPress automatically applies strict locking rules to any inner blocks nested inside a Custom HTML block. These restrictions ensure that content creators cannot inadvertently alter the structural skeleton of the design:

• No Moving: Inner blocks are locked in their designated positions and cannot be dragged or reordered.
• No Removal: Users cannot delete the nested blocks from the editor canvas or the List View.
• No Sibling Insertion: Users cannot add new blocks alongside the existing inner blocks.

This locking mechanism ensures that the surrounding HTML structure remains perfectly intact. However, the full markup remains completely accessible to developers via the “Edit HTML” modal in the block toolbar, and serialization round-trips cleanly without altering or stripping out the custom code.

Registering Custom HTML Variations with innerContent

To make this feature reusable and accessible to content creators, WordPress 7.1 introduces support for the innerContent field within block variations (specifically targeting the core/html block). This allows developers to register custom layout variations that appear directly in the block inserter.

The innerContent property accepts an array of static HTML fragments. Within this array, a null value is used as a placeholder to define exactly where the corresponding block from the innerBlocks array should be injected.

Here is an example of how to register a custom variation using this API:

wp.blocks.registerBlockVariation( 'core/html', {
    name: 'testimonial-card',
    title: 'Testimonial Card',
    icon: 'format-quote',
    innerContent: [
        '<div class="testimonial-card">',
        null,
        '</div>'
    ],
    innerBlocks: [
        [ 'core/paragraph', { content: 'An inspiring quote.' } ],
    ],
} );

When a user inserts this “Testimonial Card” variation from the inserter, WordPress generates a Custom HTML block containing the preset <div class="testimonial-card"> wrapper with an editable paragraph nested inside it. Unlike a traditional block pattern, the user is restricted to editing only the designated paragraph slot, keeping the container markup safe from accidental modification.

Practical Use Cases and AI Integration

This feature is highly beneficial for workflows involving AI-assisted content generation. Previously, if an AI model generated a complex layout with mixed HTML and text, it had to output raw HTML (which was difficult for non-technical users to edit) or attempt to output complex block serialization markup (which is prone to parsing errors).

With WordPress 7.1, an AI model can generate a single Custom HTML block that mixes arbitrary, styled markup with standard editable block placeholders. This output is immediately safe to edit in the WordPress admin panel without requiring any custom block registration, build pipelines, or complex plugin dependencies.

It also simplifies rapid prototyping for agency developers. You can quickly wrap custom CSS-grid layouts or interactive components in a Custom HTML variation, drop in standard core blocks for the content areas, and hand the site over to clients with confidence that the layout will not break.

Technical Limitations and Constraints

While this hybrid approach is highly versatile, developers should keep several technical constraints in mind during implementation:

• Exclusive to core/html: The innerContent field is strictly limited to variations of the core/html block. It is completely ignored if used with any other block type.
• No Dynamic Layout Changes: Because the outer HTML is static, you cannot dynamically change the wrapper structure based on the inner block’s settings.
• No Editor UI for Outer HTML: Content creators cannot edit the classes, attributes, or tags of the outer HTML wrapper visually; any structural changes must be done via the “Edit HTML” view.

Primary reference: Review the original announcement for exact release details. This article is an independent explanation and does not reproduce the source text.