Fix: Shortcode block does not render in Navigation Overlay

[hbhalodia]

What?

Closes #77510

Why?

• Fix the shortcode issue, Shortcode block does not render when added in navigation overlay templates.

How?

• Apply do_shortcode, exactly how render_block_core_template_part does.
• Detailed root cause added here in issue -

Testing Instructions

1. Create a sample plugin that registers a shortcode and activate it:

<?php
/**
 * Plugin Name: Test Shortcode
 * Description: Registers a [test] shortcode that prints "Hello, World!".
 * Version: 0.1.0
 */

add_shortcode(
	'test',
	static function () {
		return 'Hello, World!';
	}
);

2. Add a Shortcode block in the Navigation overlay, supplying [test] as the content.
3. Add the same Shortcode block in post content.
4. View the post on the frontend.
5. Open the Navigation Overlay on the frontend to find shortcode should be rendered.

Testing Instructions for Keyboard

• None

Screenshots or screencast

Screen.Recording.2026-04-21.at.12.01.35.PM.mov

Use of AI Tools

• GitHub Copilot.
• Model: Claude Opus 4.7
• Used to find the root cause and potential fix.
• Reviewed the code added by the model.

[Copilot]

Pull request overview

Fixes missing shortcode expansion when a core/shortcode block is placed inside a Navigation Overlay template part, bringing the overlay’s rendered output in line with how template parts typically process shortcodes.

Changes:

• Expands shortcodes in Navigation overlay template part output by applying shortcode_unautop() and do_shortcode() to the rendered overlay HTML.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: hbhalodia <hbhalodia@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>
Co-authored-by: Mathijsvdbeek <mathijsvdbeek@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[t-hamano]

Based on the processing of template parts, we need to consider whether to add some more processes in addition to shortcodes.

wptexturize(), convert_smilies(), and $wp_embed->autoembed() would likely be worth adding. wp_filter_content_tags() might not be necessary, though, as the navigation overlay is hidden by default.

[hbhalodia]

Thanks @t-hamano For the review,

Based on Claude it has to say this,

Why not wrap with the_content?
the_content also applies wpautop, wptexturize, embed autoembedding, etc., which would alter the carefully-built overlay markup (e.g. wrap structural elements in

tags, re-process images the overlay already pre-tagged with fetchpriority="low"). Matching what render_block_core_template_part() already does — just shortcode_unautop + do_shortcode — is the minimal, targeted fix consistent with how shortcodes are expanded for every other template part.

Comment - #77510 (comment)

But yes a wider team review needed here to add the functionality or not.

[t-hamano]

Matching what render_block_core_template_part() already does — just shortcode_unautop + do_shortcode

Is this true? Based on the code, render_block_core_template_part() seems to be doing more than that.

gutenberg/packages/block-library/src/template-part/index.php

Lines 152 to 168 in e406c2b

	// Run through the actions that are typically taken on the_content.
	$content = shortcode_unautop( $content );
	$content = do_shortcode( $content );
	$seen_ids[ $template_part_id ] = true;
	$content = do_blocks( $content );
	unset( $seen_ids[ $template_part_id ] );
	$content = wptexturize( $content );
	$content = convert_smilies( $content );
	$content = wp_filter_content_tags( $content, "template_part_{$area}" );
	/**
	* Handle embeds for block template parts.
	*
	* @global WP_Embed $wp_embed WordPress Embed object.
	*/
	global $wp_embed;
	$content = $wp_embed->autoembed( $content );

[t-hamano]

@hbhalodia, can you check #77511 (comment)?

[hbhalodia]

Matching what render_block_core_template_part() already does — just shortcode_unautop + do_shortcode

Is this true? Based on the code, render_block_core_template_part() seems to be doing more than that.

gutenberg/packages/block-library/src/template-part/index.php

Lines 152 to 168 in e406c2b

	// Run through the actions that are typically taken on the_content.
	$content = shortcode_unautop( $content );
	$content = do_shortcode( $content );
	$seen_ids[ $template_part_id ] = true;
	$content = do_blocks( $content );
	unset( $seen_ids[ $template_part_id ] );
	$content = wptexturize( $content );
	$content = convert_smilies( $content );
	$content = wp_filter_content_tags( $content, "template_part_{$area}" );
	/**
	* Handle embeds for block template parts.
	*
	* @global WP_Embed $wp_embed WordPress Embed object.
	*/
	global $wp_embed;
	$content = $wp_embed->autoembed( $content );

Thanks @t-hamano for the review and sorry for the delay here in answering this.

Since the PR used claude to identify the root cause and a fix for the same, I asked it why we are just using 2 function and not the other functions as above,

Here is the response from claude, which it seems valid, but need more higher review from the team,

Of the seven steps in render_block_core_template_part(), only one (shortcode_unautop + do_shortcode) addresses a missing transformation for the overlay path. The rest are either already performed earlier in the overlay pipeline (do_blocks, image optimization) or are prose-oriented filters (wptexturize, convert_smilies, autoembed) whose inclusion would alter structural overlay markup without fixing the reported bug. The minimal fix restores shortcode expansion — which is what #77510 is specifically about — and nothing more.

Detailed response

In render_block_core_template_part(), this full pipeline is applied to raw content:

For Navigation overlay template parts, execution is different:

• get_overlay_blocks_from_template_part() already parses blocks.
• get_template_part_blocks_html() already renders each block via $block->render().
• Then overlay-specific post-processing runs (close-button detection, directives, image fetchpriority handling).

So by this point, we are not at the raw-content stage anymore.

1. shortcode_unautop() + do_shortcode()
   Needed and missing.
   core/shortcode outputs shortcode text; expansion is expected later.
   In post content, that happens via the_content filter; in normal template parts, it happens inside render_block_core_template_part().
   In overlay rendering, neither path runs, so shortcode text remains unexpanded unless we add these two calls.

2. $seen_ids[...] recursion guard
   Not needed here.
   This guard exists for template-part recursion during do_blocks() in render_block_core_template_part().
   Overlay code is not invoking that same recursion path.

3. do_blocks()
   Already effectively done upstream in overlay flow.
   Overlay blocks are already parsed and rendered via $block->render().
   Re-running do_blocks() here would be redundant and risks double-processing.

4. wptexturize() / convert_smilies()
   Intentionally not added.
   These are prose-oriented transforms and not required to fix shortcode rendering.
   Applying them on assembled overlay HTML can introduce unrelated output changes.

5. wp_filter_content_tags()
   Not needed here and already accounted for by overlay logic.
   Overlay code already handles image fetch-priority behavior specifically for hidden overlay content (block_core_navigation_set_overlay_image_fetch_priority()), designed to cooperate with later content-tag processing in the parent template context.

Bottom line

The bug is specifically: shortcodes in overlay template parts are not expanded.
The minimal, targeted fix is to add exactly:

$overlay_blocks_html = shortcode_unautop( $overlay_blocks_html );
$overlay_blocks_html = do_shortcode( $overlay_blocks_html );

Thanks to copilot and claude to remember the session that was added few weeks back 😄.

Still need manual verification from the wider team on to include the other functions or not.

[hbhalodia]

@hbhalodia, can you check #77511 (comment)?

Was answering the same, just hit re-review button before adding the comment. Sorry!

[t-hamano]

@hbhalodia Thanks for the reply!

Upon further investigation, I have confirmed that shortcode_unautop and do_shortcode are indeed sufficient.

However, it is important where it is processed. In normal template parts, shortcodes are processed before the block is parsed. On the other hand, in this PR, shortcodes are processed after the block within the navigation overlay is parsed. This may result in different final rendered HTML outputs depending on the template part.

For example, try inserting the following shortcode into both the normal template part and the overlay template part.

add_shortcode( 'test', function() {
	return '<span class="test">Shortcode Test</span>';
} );

The final rendered HTML differs as follows.

Normal Template Part:

<p><span class="test">Shortcode Test</span></p>

Overlay Template Part:

<span class="test">Shortcode Test</span>

To resolve this discrepancy, it might be better to process shortcodes before parsing blocks in the overlay template part as well.

diff --git a/packages/block-library/src/navigation/index.php b/packages/block-library/src/navigation/index.php
index 72eefc7ce05..9da5d75cabe 100644
--- a/packages/block-library/src/navigation/index.php
+++ b/packages/block-library/src/navigation/index.php
@@ -425,7 +425,11 @@ class WP_Navigation_Block_Renderer {
                        $full_template_part_id = $theme . '//' . $slug;
                        $block_template        = get_block_file_template( $full_template_part_id, 'wp_template_part' );
                        if ( isset( $block_template->content ) ) {
-                               $parsed_blocks = parse_blocks( $block_template->content );
+                               // Expand shortcodes before parsing blocks, matching the order in
+                               // `render_block_core_template_part()`.
+                               $content       = shortcode_unautop( $block_template->content );
+                               $content       = do_shortcode( $content );
+                               $parsed_blocks = parse_blocks( $content );
                                $blocks        = block_core_navigation_filter_out_empty_blocks( $parsed_blocks );
                                // Disable overlay menu for any navigation blocks within the overlay to prevent nested overlays.
                                $blocks = static::disable_overlay_menu_for_nested_navigation_blocks( $blocks );
@@ -449,6 +453,12 @@ class WP_Navigation_Block_Renderer {
                // Re-serialize, and run Block Hooks algorithm to inject hooked blocks.
                $markup = serialize_blocks( $blocks );
                $markup = apply_block_hooks_to_content_from_post_object( $markup, $template_part_post );
+
+               // Expand shortcodes before parsing blocks, matching the order in
+               // `render_block_core_template_part()`.
+               $markup = shortcode_unautop( $markup );
+               $markup = do_shortcode( $markup );
+
                $blocks = parse_blocks( $markup );
 
                // Disable overlay menu for any navigation blocks within the overlay to prevent nested overlays.
@@ -700,11 +710,6 @@ class WP_Navigation_Block_Renderer {
                        // Render template part blocks directly without navigation container wrapper.
                        $overlay_blocks_html = static::get_template_part_blocks_html( $overlay_blocks );
 
-                       // Expand shortcodes in the overlay, matching what `render_block_core_template_part()`
-                       // does for regular template parts. See https://github.com/WordPress/gutenberg/issues/77510.
-                       $overlay_blocks_html = shortcode_unautop( $overlay_blocks_html );
-                       $overlay_blocks_html = do_shortcode( $overlay_blocks_html );
-
                        // Check if overlay contains a navigation-overlay-close block (detect in rendered HTML so it works with patterns).
                        $has_custom_overlay_close_block = block_core_navigation_overlay_html_has_close_block( $overlay_blocks_html );
                        // Add Interactivity API directives to the overlay close block if present.

[hbhalodia]

Thanks @t-hamano for the detailed analysis. I will check the above and update the PR as needed. I will test based on the shared findings.

[hbhalodia]

Hi @t-hamano, Thanks for the verification above.

I do have tested it on my end by adding the shortcode in normal template part and navigation overlay. I can confirm after the change both are providing the same output in terms of markup generation.

[t-hamano]

LGTM!

[github-actions]

I just cherry-picked this PR to the wp/7.0 branch to get it included in the next release: 79d4258