Insert block template skip link via HTML API, minify CSS, remove JS. #10676

rutviksavsani · 2026-01-01T09:29:11Z

Move the block template skip link from client-side injection to server-side HTML processing using the HTML API, while keeping the existing accessibility behaviour and minifying the CSS.

What this changes

Adds _block_template_skip_link_markup() to process the block template HTML:
- Ensures the first <main> has an id (adds wp--skip-link--target if missing).
- Inserts a single <a id="wp-skip-link" class="skip-link screen-reader-text"> before .wp-site-blocks.
- Skips insertion when there is no <main> or when a skip link already exists.
Updates get_the_block_template_html() to run the rendered template through the new helper.
Refactors wp_enqueue_block_template_skip_link() to:
- Remove the old JS-based DOM injection.
- Minify the skip-link CSS as an inline style.
Preserves backward compatibility gating via the_block_template_skip_link and block-templates theme support.
Add tests for the new function as well.

Ticket

Trac ticket: https://core.trac.wordpress.org/ticket/64361

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

github-actions · 2026-01-01T09:29:21Z

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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props rutviksavsani, westonruter, dmsnell.

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

github-actions · 2026-01-01T09:43:28Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

The Plugin and Theme Directories cannot be accessed within Playground.
All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

westonruter

Great to see this!

src/wp-includes/block-template.php

Co-authored-by: Weston Ruter <[email protected]>

src/wp-includes/theme-templates.php

tests/phpunit/tests/block-template-utils.php

…into refact/insert-skip-link-via-html

westonruter

This is looking great! I'll await a second review from @dmsnell before committing.

src/wp-includes/block-template.php

src/wp-includes/css/wp-block-template-skip-link.css

src/wp-includes/block-template.php

dmsnell · 2026-01-07T21:08:15Z

src/wp-includes/block-template.php

+ * Inserts the block template skip link into the template HTML.
+ *
+ * Uses the HTML API to ensure that the main content element has an ID and to
+ * inject the skip-link anchor before the block template wrapper.


as much as I love this, I’m not sure we need to describe in the docblock how the function operates. we can probably clarify the goal, which is well-stated here, and give an illustrative example.

/** * ... * * When a `MAIN` element exists in the template, this function will ensure * that the element contains a `id` attribute and will insert a link to * that main element at the top of the first `DIV.wp-site-blocks` match. * * Example: * * // Input. * <main> * <nav>...</nav> * <div class="wp-site-blocks"> * <h2>... * * // Output. * <main id="wp--skip-link--target"> * <nav>...</nav> * <div class="wp-site-blocks"> * <a href="#wp--skip-link--target" id="wp-skip-link" class="..."> * <h2>... * * When the `MAIN` element already contains a non-empty `id` value it will be * used instead of the default skip-link id.

dmsnell · 2026-01-07T21:09:53Z

src/wp-includes/block-template.php

+	// Back-compat for plugins that disable functionality by unhooking this action.
+	if ( ! has_action( 'wp_footer', 'the_block_template_skip_link' ) ) {
+		return $template_html;
+	}


It seems like we could move this check up into get_the_block_template_html() which would leave this function considerably more declarative and stable. with the check here it’s leading us to create the awkward Closure-passing for test setup because the function is stateful with the system.

dmsnell · 2026-01-07T21:21:13Z

src/wp-includes/block-template.php

+			$skip_link_target_id = 'wp--skip-link--target';
+			$processor->set_attribute( 'id', $skip_link_target_id );
+		}
+	}


if we’re going to default to a given value, we could set it first and only change if we find one already exists.

// Only add skip-links to templates with a MAIN element. if ( ! $processor->next_tag( 'MAIN' ) ) { return $template_html; } $target_id = $processor->get_attribute( 'id' ); if ( ! is_string( $target_id ) && '' === $target_id ) { $target_id = 'wp--skip-link--target' $processor->set_attribute( 'id', $target_id ); } ...

Note too that I did not use trim() in my example. This is a secondary mention, but it’s not appropriate for us to trim() an id attribute’s value, as “Identifiers are opaque strings.” (HTML spec).

we can see differentiation between id values with different whitespace.

<p id="me">one</p> <p id=" me">two</p> <p id="me ">three</p> <p id=" me ">four</p> <style> #me { border: 1px solid blue; } #\20me { border: 1px solid green; } #me\20 { border: 1px solid red; } #\20me\20 { border: 1px solid orange; } </style>

In other words, the trim() will cause WordPress to misidentify the id and break the skip-link any time it would ever make a difference in the code.

westonruter · 2026-01-07T21:27:31Z

@rutviksavsani Could you address that great feedback from Dennis?

dmsnell · 2026-01-07T21:45:10Z

tests/phpunit/tests/block-template-utils.php

+			'action_removed'                             => array(
+				'set_up'        => static function () {
+					remove_action( 'wp_footer', 'the_block_template_skip_link' );
+				},


GitHub appears to have lost my comment again so I’ll try and resubmit it here, but I might be missing things this second time around.

I find this Closure-passing to be a bit confusing and opaque, particularly because the test code doesn’t give any clue as to what’s happening. it’s also interesting that only a single test case has setup code and only does a single thing.

one way to clear this up would be to pass the setup intention as a name, like with-filter or without-filter. but I think another step would be even clearer, since it appears that the goal is to ensure this doesn’t add a skip link under certain circumstances: split the test into separate functions.

public function test_block_template_properly_adds_skip_link( string $template_html, string $html_with_skip_link ) { } public function test_block_template_only_adds_skip_link_when_main_element_present() { $template_html = "<main>...</main>"; ... $this->assertEqualMarkup( "<main id='...'>...<div class='...'><a href='...'>", _block_template_skip_link_markup( $template_html ) ); $template_html = "..."; // without MAIN ... $this->assertSame( $template_html, _block_template_skip_link_markup( $template_html ) ); } public function test_block_template_only_adds_skip_link_when_filter_present() { $template_html = "<main>...</main>"; $this->assertEqualMarkup( ... ); remove_action( 'wp_footer', 'the_block_template_skip_link' ); $this->assertSame( $template_html, get_the_block_template_html() ); }

I’ve omitted important details in this code snippet because I only wanted to show the idea of creating separate named tests to assert specific behaviors. in this way, the tests that fail will more closely match the behaviors that change and the test setup will/should be clearer.

obviously if the has_action() check moves up into get_the_block_template_html() function there’s an extra bit of setup code to make sure we can inject the $template_html into it, but that leaves _block_template_skip_link_markup() easier to test in isolation. this is a tradeoff that’s less significant than splitting the test.

rutviksavsani · 2026-01-08T14:42:30Z

@westonruter @dmsnell I have implemented the suggestions with best of my understandings, Let me know if I missed anything.

dmsnell

Coming along quite well. I don‘t mean to delay this any more, but I left a couple of comments for your consideration.

Combining the processors into one, using the subclass, could have meaningful performance implications given that we are currently parsing the part of the post twice, up until the MAIN element.

dmsnell · 2026-01-08T16:57:23Z

src/wp-includes/block-template.php

+			$inserter->insert_before( $skip_link );
+			break;
+		}
+	}


it’s now more clear to me that this entire loop can be collapsed into another single if because we’re looking unconditionally for the first DIV.wp-site-blocks. That means the built-in query fully supports our goal.

if ( $inserter->next_tag( array( 'tag_name' => 'DIV', 'class_name' => 'wp-site-blocks' ) ) ) { $skip_link = ... $inserter->insert_before( $skip_link ); break; }

yes, this makes sense, implementing it in the next commit.

dmsnell · 2026-01-08T17:01:13Z

src/wp-includes/block-template.php

+			$this->set_bookmark( 'here' );
+			$this->lexical_updates[] = new WP_HTML_Text_Replacement( $this->bookmarks['here']->start, 0, $text );
+		}
+	};


One fun thing about subclassing is that you can use all the existing mechanisms of the underlying HTML API. If you wanted to, instead of creating a separate processor for finding the MAIN id and then inserting a skip link, we could simply create $processor itself as the subclass instance.

There are two added benefits I see:

Don’t need to create $template_html = $processor->get_updated_html().

Don’t need to double-traverse the entire post to find the DIV again.

Of course, if we expect the DIV.wp-site-blocks to appear before the MAIN then we have to start over our traversal (though we could bookmark it on the way to finding the MAIN element), but I think that’s moot because we probably expect it to follow the MAIN don’t we?

We do actually expect DIV.wp-site-blocks to appear before the MAIN. This is the expected structure:

The get_the_block_template_html() function adds DIV.wp-site-blocks as a wrapper around everything:

wordpress-develop/src/wp-includes/block-template.php

Lines 302 to 304 in 5a53b94

// Wrap block template in .wp-site-blocks to allow for specific descendant styles

// (e.g. `.wp-site-blocks > *`).

return '<div class="wp-site-blocks">' . $content . '</div>';

wordpress-develop/src/wp-includes/template-canvas.php

Lines 12 to 23 in 5a53b94

$template_html = get_the_block_template_html();

?><!DOCTYPE html>

<html <?php language_attributes(); ?>>

<head>

<meta charset="<?php bloginfo( 'charset' ); ?>" />

<?php wp_head(); ?>

</head>

<body <?php body_class(); ?>>

<?php wp_body_open(); ?>

<?php echo $template_html; ?>

great, thanks for clarifying. I did not know.

in that case, we can still reap the same benefit just by setting a bookmark on the DIV, then seeking back to it after finding the MAIN

yes, this makes sense, implementing it in the next commit.

rutviksavsani · 2026-01-09T07:13:52Z

@dmsnell I have added the changes and looks good to me with what we wanted to achieve. Let me know if it looks good to you.

dmsnell · 2026-01-09T07:23:20Z

src/wp-includes/block-template.php

+	// Ensure the MAIN element has an ID.
+	if ( ! $processor->next_tag( 'MAIN' ) ) {
+		return $template_html;
+	}


I think this is covered by what @westonruter wrote, but one final check on this is whether we certain of the ordering of the DIV and MAIN elements. If we are, then no work is required. If, on the other hand, there could be cases where they are backwards, we would rather want to combine these two scan operations into a single loop.

Given the amount of feedback on this already, I hope this sounds more helpful than tedious. I’m seeing these changes in new ways each time you update them; thank you for this valuable contribution and your perseverance in iterating on it.

$found_div = false; $target_id = null; while ( ! $found_div && ! isset( $target_id ) && $processor->next_tag() ) { switch ( $processor->get_tag() ) { case 'DIV': if ( ! $found_div && $processor->has_class( 'wp-site-blocks' ) ) { $found_div = $processor->set_bookmark( '...' ); } break; case 'MAIN': if ( ! isset( $target_id ) ) { $target_id = $processor->get_attribute( 'id' ); if ( ! is_string( ... ) || '' === $target_id ) { $target_id = '...'; $processor->set_attribute( 'id', $target_id ); } } break; } } if ( ! ( $found_div && isset( $target_id ) ) ) { return $template_html; }

Yes, I thought of that initially but with my experience of sites I have looked into and worked on the block template, it seems to be always consistent. but will differ to opinion from you both as you would have more experience into different kind of site variations we may have as WordPress is not limited to a few.

If we feel we may need to check both ways, I can implement your suggestion as well. But will wait on @westonruter opinion as well if that is required.

Really grateful for the thorough review as well as it has been long time, I worked on Core issues 🙌

The DIV.site-blocks should always be the wrapper of the MAIN given what I shared in #10676 (comment).

Perfect, Thanks.
Then I assume we are good to go ahead with this PR right, with what we have.

westonruter · 2026-01-09T07:56:41Z

I'm confused why the Tests_Template::test_wp_hoist_late_printed_styles are failing. They pass for my locally.

I'm also seeing a problem on the frontend with how the sourceURL comment is being constructed for the new style. I see:

/*# sourceURL=http://wp-includes/css/wp-block-template-skip-link.css */

rutviksavsani · 2026-01-09T08:10:08Z

I'm confused why the Tests_Template::test_wp_hoist_late_printed_styles are failing. They pass for my locally.

I'm also seeing a problem on the frontend with how the sourceURL comment is being constructed for the new style. I see:
/*# sourceURL=http://wp-includes/css/wp-block-template-skip-link.css */

Look's okay to me on local as well for the sourceURL. Tests failure I am not completely sure of on what it can be but it's failing on other PRs on the repo as well.

westonruter · 2026-01-09T08:18:39Z

Tests failure I am not completely sure of on what it can be but it's failing on other PRs on the repo as well.

I'm not seeing test failures for the latest commit in trunk: https://github.com/WordPress/wordpress-develop/actions/runs/20841211620/job/59875830100

No test failures in this PR either: #10694

Something is wrong with that Tests_Template::test_wp_hoist_late_printed_styles test. I'll have to debug it tomorrow.

westonruter · 2026-01-09T08:27:32Z

Look's okay to me on local as well for the sourceURL.

I fixed this at least in 350b57c.

This now matches the existing code better:

wordpress-develop/src/wp-includes/script-loader.php

Lines 1639 to 1645 in 76ca772

    
           $block_library_theme_path = WPINC . "/css/dist/block-library/theme$suffix.css"; 
        
           $styles->add( 'wp-block-library-theme', "/$block_library_theme_path" ); 
        
           $styles->add_data( 'wp-block-library-theme', 'path', ABSPATH . $block_library_theme_path ); 
        
           $classic_theme_styles_path = WPINC . "/css/classic-themes$suffix.css"; 
        
           $styles->add( 'classic-theme-styles', "/$classic_theme_styles_path" ); 
        
           $styles->add_data( 'classic-theme-styles', 'path', ABSPATH . $classic_theme_styles_path );

I now see:

/*# sourceURL=/wp-includes/css/wp-block-template-skip-link.css */

dmsnell · 2026-01-09T09:12:10Z

src/wp-includes/block-template.php

+ *         <nav>...</nav>
+ *         <div class="wp-site-blocks">
+ *             <a href="#wp--skip-link--target" id="wp-skip-link" class="...">
+ *             <h2>...


this example should be updated to reflect the proper HTML markup we expect, including but limited to showing that the DIV comes first

Insert block template skip link via HTML API, minify CSS, remove JS.

8e7719a

westonruter requested changes Jan 2, 2026

View reviewed changes

rutviksavsani and others added 6 commits January 3, 2026 12:54

remove extra checks for block template.

7e29956

Co-authored-by: Weston Ruter <[email protected]>

Add type and return type to the function.

908f6a9

Co-authored-by: Weston Ruter <[email protected]>

Update translators comment.

d6278d3

Co-authored-by: Weston Ruter <[email protected]>

Add extra checks for get_attribute link target.

9a73e67

Co-authored-by: Weston Ruter <[email protected]>

update function doc comment.

a62dffb

Co-authored-by: Weston Ruter <[email protected]>

Remove the duplication check and tag closers check.

43c4b01

rutviksavsani requested a review from westonruter January 3, 2026 08:19

westonruter reviewed Jan 3, 2026

View reviewed changes

src/wp-includes/theme-templates.php Outdated Show resolved Hide resolved

westonruter requested a review from dmsnell January 3, 2026 08:26

css concat but make it still readable.

ce8885a

rutviksavsani requested a review from westonruter January 5, 2026 06:19

westonruter added 2 commits January 4, 2026 22:23

Remove single-use private method

cd9e029

Add since tag to wp_enqueue_block_template_skip_link()

a194ca8

westonruter reviewed Jan 5, 2026

View reviewed changes

src/wp-includes/theme-templates.php Outdated Show resolved Hide resolved

westonruter reviewed Jan 5, 2026

View reviewed changes

tests/phpunit/tests/block-template-utils.php Outdated Show resolved Hide resolved

address feedback.

6b7841c

rutviksavsani requested a review from westonruter January 5, 2026 09:53

westonruter added 8 commits January 5, 2026 09:39

Add missing path data for stylesheet

0bb3ec4

Leverage assertEqualHTML

c340b2c

Add test case for removal of the_block_template_skip_link from wp_footer

eff4489

Tweak comment

b00b244

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

1ae2bb2

…into refact/insert-skip-link-via-html

Fix swapped test names

d179f23

Replace while loop with if statement

540b526

Use data provider

746e686

westonruter added 2 commits January 5, 2026 10:27

Add test cases for malformed IDs

45c26b8

Remove unnecessary variable

c565ff9

westonruter approved these changes Jan 5, 2026

View reviewed changes

dmsnell reviewed Jan 7, 2026

View reviewed changes

src/wp-includes/block-template.php Outdated Show resolved Hide resolved

dmsnell reviewed Jan 7, 2026

View reviewed changes

src/wp-includes/css/wp-block-template-skip-link.css Show resolved Hide resolved

westonruter reviewed Jan 7, 2026

View reviewed changes

src/wp-includes/block-template.php Outdated Show resolved Hide resolved

dmsnell reviewed Jan 7, 2026

View reviewed changes

src/wp-includes/block-template.php Outdated Show resolved Hide resolved

Use esc_url() instead of esc_attr()

ce5b88e

dmsnell reviewed Jan 7, 2026

View reviewed changes

src/wp-includes/block-template.php Outdated Show resolved Hide resolved

dmsnell reviewed Jan 7, 2026

View reviewed changes

rutviksavsani added 2 commits January 8, 2026 19:20

Block template skip link handling

8b83d4e

Add tests for block template skip link

d066dc4

dmsnell reviewed Jan 8, 2026

View reviewed changes

westonruter mentioned this pull request Jan 8, 2026

Add view transitions in WP Admin #10699

Open

Remove the extra processor loop and use seek to insert link.

64ff9d1

dmsnell reviewed Jan 9, 2026

View reviewed changes

Merge branch 'WordPress:trunk' into refact/insert-skip-link-via-html

64a8b4a

Fix URL for wp-block-template-skip-link

350b57c

dmsnell reviewed Jan 9, 2026

View reviewed changes

	// Wrap block template in .wp-site-blocks to allow for specific descendant styles
	// (e.g. `.wp-site-blocks > *`).
	return '<div class="wp-site-blocks">' . $content . '</div>';

	$template_html = get_the_block_template_html();
	?><!DOCTYPE html>
	<html <?php language_attributes(); ?>>
	<head>
	<meta charset="<?php bloginfo( 'charset' ); ?>" />
	<?php wp_head(); ?>
	</head>

	<body <?php body_class(); ?>>
	<?php wp_body_open(); ?>

	<?php echo $template_html; ?>

Insert block template skip link via HTML API, minify CSS, remove JS. #10676

Are you sure you want to change the base?

Insert block template skip link via HTML API, minify CSS, remove JS. #10676

Conversation

rutviksavsani commented Jan 1, 2026

What this changes

Ticket

Uh oh!

github-actions bot commented Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 1, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

westonruter commented Jan 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rutviksavsani commented Jan 8, 2026

Uh oh!

dmsnell left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rutviksavsani commented Jan 9, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 1, 2026 •

edited

Loading