Leverage HTML API to implement block template skip link

[Slieptsov]

When the_block_template_skip_link() (now wp_enqueue_block_template_skip_link()) was introduced in #53176 there was no HTML API which necessitated JavaScript to add the skip link. This can now be revisited to leverage WP_HTML_Tag_Processor to add the skip link.

The inline JavaScript can then be eliminated.

The CSS should also be minified.

---

Original description:

Can skip link CSS/JS be minified?

​https://github.com/WordPress/wordpress-develop/blob/0b50baa5d164bedd17d3ae9e2eafc6286d6255b6/src/wp-includes/theme-templates.php#L172

[westonruter]

What's more is that I don't think this needs to use JavaScript at all anymore. The HTML API can be used to make the markup modifications. This could be done in get_the_block_template_html().

This was first introduced in r51003 (#53176) and was revisited in r56932 (#59505).

[anton7249]

Ok, got it, thanks.

[whiteshadow01]

The HTML API doesn't allow inserting elements into the DOM, only modifying the existing ones. How do we plan on inserting a new anchor tag as we are doing it in the javascript right now using the HTML API?

[westonruter]

@whiteshadow01 It does, but not via the public interface. You can see an example of this in wp_hoist_late_printed_styles(). See ​these lines.

[whiteshadow01]

Thanks @westonruter

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

@rutviksavsani Could you address that great feedback from Dennis?

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

@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.

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 */

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.

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: ​https://github.com/WordPress/wordpress-develop/pull/10694

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

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:

​https://github.com/WordPress/wordpress-develop/blob/76ca7726a951f35e3693b54f65c376ecd399df37/src/wp-includes/script-loader.php#L1639-L1645

I now see:

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

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

Fixed in 61711e2716742d44a86c5b26477cad4d74edac83. The problem is that some other test in the test suite is not cleaning up after itself. When the test runs in isolation, it's not a block template. But some other test is leaving the block template status in place. Previously the code was already ignoring wp-block-template-skip-link-inline-css for this reason. It was failing for wp-block-template-skip-link-css because now since the stylesheet is actually in the filesystem, it can be conditionally _not_ inlined, as is being done in the tests.

I cURL'ed the Sample Page before and after the change and here's the diff:

.html

@@ -2478 +2478 @@
         width: auto;
         z-index: 100000;
       }
-      /*# sourceURL=wp-block-template-skip-link-inline-css */
+
+      /*# sourceURL=/wp-includes/css/wp-block-template-skip-link.css */
     </style>
     <style id="twentytwentyfive-style-inline-css">
       /*
@@ -2628 +2629 @@
   <body
     class="wp-singular page-template-default page page-id-2 wp-embed-responsive wp-theme-twentytwentyfive"
   >
+    <a
+      class="skip-link screen-reader-text"
+      id="wp-skip-link"
+      href="#wp--skip-link--target"
+      >Skip to content</a
+    >
     <div class="wp-site-blocks">
       <header class="wp-block-template-part">
         <div
@@ -2765 +2772 @@
       </header>
 
       <main
+        id="wp--skip-link--target"
         class="wp-block-group has-global-padding is-layout-constrained wp-block-group-is-layout-constrained"
         style="margin-top: var(--wp--preset--spacing--60)"
       >
@@ -3013 +3021 @@
       fetchpriority="low"
       data-wp-router-options='{"loadOnClientNavigation":true}'
     ></script>
-    <script id="wp-block-template-skip-link-js-after">
-      (function () {
-        var skipLinkTarget = document.querySelector("main"),
-          sibling,
-          skipLinkTargetID,
-          skipLink;
-
-        // Early exit if a skip-link target can't be located.
-        if (!skipLinkTarget) {
-          return;
-        }
-
-        /*
-         * Get the site wrapper.
-         * The skip-link will be injected in the beginning of it.
-         */
-        sibling = document.querySelector(".wp-site-blocks");
-
-        // Early exit if the root element was not found.
-        if (!sibling) {
-          return;
-        }
-
-        // Get the skip-link target's ID, and generate one if it doesn't exist.
-        skipLinkTargetID = skipLinkTarget.id;
-        if (!skipLinkTargetID) {
-          skipLinkTargetID = "wp--skip-link--target";
-          skipLinkTarget.id = skipLinkTargetID;
-        }
-
-        // Create the skip link.
-        skipLink = document.createElement("a");
-        skipLink.classList.add("skip-link", "screen-reader-text");
-        skipLink.id = "wp-skip-link";
-        skipLink.href = "#" + skipLinkTargetID;
-        skipLink.innerText = "Skip to content";
-
-        // Inject the skip link.
-        sibling.parentElement.insertBefore(skipLink, sibling);
-      })();
-
-      //# sourceURL=wp-block-template-skip-link-js-after
-    </script>
     <script id="wp-emoji-settings" type="application/json">
       {
         "baseUrl": "https://s.w.org/images/core/emoji/17.0.2/72x72/",

I just realized another benefit to doing this: the skip link works even when JavaScript is turned off.

I just noticed that RTL versions of the CSS files are being generated. Here are all the versions now after a build:

• src/wp-includes/css/wp-block-template-skip-link-rtl.css
• src/wp-includes/css/wp-block-template-skip-link-rtl.min.css
• src/wp-includes/css/wp-block-template-skip-link.css
• src/wp-includes/css/wp-block-template-skip-link.min.css

Previously there was no RTL variation in the CSS. So maybe this was a bug. But it doesn't seem the RTL version is currently getting registered so it is being unused. We need to double check that.

Indeed, this is an issue. The skip link is not getting positioned on the right as expected in Arabic:

English | Arabic

--

|

OK, with 357ea8ac2177aa34c4b436b2d47ac7132303975a I now get the skip link positioned on the right as expected, but only when styles_inline_size_limit is zero. I then get this stylesheet in the HTML:

<link rel='stylesheet' id='wp-block-template-skip-link-rtl-css' href='http://localhost:8000/wp-includes/css/wp-block-template-skip-link-rtl.min.css?ver=7.0-alpha-61215-src' media='all' />

But when SCRIPT_DEBUG is off and styles_inline_size_limit is at the default of 40K, I see:

<style id="wp-block-template-skip-link-inline-css">
.skip-link.screen-reader-text {
        border: 0;
        clip-path: inset(50%);
        height: 1px;
        margin: -1px;
        overflow: hidden;
        padding: 0;
        position: absolute !important;
        width: 1px;
        word-wrap: normal !important;
}

.skip-link.screen-reader-text:focus {
        background-color: #eee;
        clip-path: none;
        color: #444;
        display: block;
        font-size: 1em;
        height: auto;
        left: 5px;
        line-height: normal;
        padding: 15px 23px 14px;
        text-decoration: none;
        top: 5px;
        width: auto;
        z-index: 100000;
}

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

Note the erroneous left: 5px. It should have right: 5px; which I can see in wp-block-template-skip-link-rtl.css.

It turns out this is a known issue which doesn't have to be fixed in this PR: Core-61625. It's already something on my radar, so I'll follow up on that now that I've seen another example of how to reproduce it. At least it's fixed when stylesheet inlining is disabled.

The diff above in ​https://github.com/WordPress/wordpress-develop/pull/10676#issuecomment-3733991892 was with prettier applied. Here's the diff with SCRIPT_DEBUG off and no prettier formatting. Notice how the CSS is now minified:

.html

@@ -97 +97 @@
 /*# sourceURL=core-block-supports-inline-css */
 </style>
 <style id="wp-block-template-skip-link-inline-css">
-
-                .skip-link.screen-reader-text {
-                        border: 0;
-                        clip-path: inset(50%);
-                        height: 1px;
-                        margin: -1px;
-                        overflow: hidden;
-                        padding: 0;
-                        position: absolute !important;
-                        width: 1px;
-                        word-wrap: normal !important;
-                }
-
-                .skip-link.screen-reader-text:focus {
-                        background-color: #eee;
-                        clip-path: none;
-                        color: #444;
-                        display: block;
-                        font-size: 1em;
-                        height: auto;
-                        left: 5px;
-                        line-height: normal;
-                        padding: 15px 23px 14px;
-                        text-decoration: none;
-                        top: 5px;
-                        width: auto;
-                        z-index: 100000;
-                }
-/*# sourceURL=wp-block-template-skip-link-inline-css */
+/*! This file is auto-generated */
+.skip-link.screen-reader-text{border:0;clip-path:inset(50%);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute!important;width:1px;word-wrap:normal!important}.skip-link.screen-reader-text:focus{background-color:#eee;clip-path:none;color:#444;display:block;font-size:1em;height:auto;left:5px;line-height:normal;padding:15px 23px 14px;text-decoration:none;top:5px;width:auto;z-index:100000}
+/*# sourceURL=/wp-includes/css/wp-block-template-skip-link.min.css */
 </style>
 <style id="twentytwentyfive-style-inline-css">
 a{text-decoration-thickness:1px!important;text-underline-offset:.1em}:where(.wp-site-blocks :focus){outline-width:2px;outline-style:solid}.wp-block-navigation .wp-block-navigation-submenu .wp-block-navigation-item:not(:last-child){margin-bottom:3px}.wp-block-navigation .wp-block-navigation-item .wp-block-navigation-item__content{outline-offset:4px}.wp-block-navigation .wp-block-navigation-item ul.wp-block-navigation__submenu-container .wp-block-navigation-item__content{outline-offset:0}blockquote,caption,figcaption,h1,h2,h3,h4,h5,h6,p{text-wrap:pretty}.more-link{display:block}:where(pre){overflow-x:auto}
@@ -147 +121 @@
 
 <body class="wp-singular page-template-default page page-id-2 wp-embed-responsive wp-theme-twentytwentyfive">
 
-<div class="wp-site-blocks"><header class="wp-block-template-part">
+<a class="skip-link screen-reader-text" id="wp-skip-link" href="#wp--skip-link--target">Skip to content</a><div class="wp-site-blocks"><header class="wp-block-template-part">
 <div class="wp-block-group alignfull is-layout-flow wp-block-group-is-layout-flow">
         
         <div class="wp-block-group has-global-padding is-layout-constrained wp-block-group-is-layout-constrained">
@@ -198 +172 @@
 </header>
 
 
-<main class="wp-block-group has-global-padding is-layout-constrained wp-block-group-is-layout-constrained" style="margin-top:var(--wp--preset--spacing--60)">
+<main id="wp--skip-link--target" class="wp-block-group has-global-padding is-layout-constrained wp-block-group-is-layout-constrained" style="margin-top:var(--wp--preset--spacing--60)">
         
         <div class="wp-block-group alignfull has-global-padding is-layout-constrained wp-block-group-is-layout-constrained" style="padding-top:var(--wp--preset--spacing--60);padding-bottom:var(--wp--preset--spacing--60)">
                 
@@ -298 +272 @@
 {"prefetch":[{"source":"document","where":{"and":[{"href_matches":"/*"},{"not":{"href_matches":["/wp-*.php","/wp-admin/*","/wp-content/uploads/*","/wp-content/*","/wp-content/plugins/*","/wp-content/themes/twentytwentyfive/*","/*\\?(.+)"]}},{"not":{"selector_matches":"a[rel~=\"nofollow\"]"}},{"not":{"selector_matches":".no-prefetch, .no-prefetch a"}}]},"eagerness":"conservative"}]}
 </script>
 <script type="module" src="http://localhost:8000/wp-includes/js/dist/script-modules/block-library/navigation/view.min.js?ver=7437ed5c45ee57daf02c" id="@wordpress/block-library/navigation/view-js-module" fetchpriority="low" data-wp-router-options="{&quot;loadOnClientNavigation&quot;:true}"></script>
-<script id="wp-block-template-skip-link-js-after">
-        ( function() {
-                var skipLinkTarget = document.querySelector( 'main' ),
-                        sibling,
-                        skipLinkTargetID,
-                        skipLink;
-
-                // Early exit if a skip-link target can't be located.
-                if ( ! skipLinkTarget ) {
-                        return;
-                }
-
-                /*
-                 * Get the site wrapper.
-                 * The skip-link will be injected in the beginning of it.
-                 */
-                sibling = document.querySelector( '.wp-site-blocks' );
-
-                // Early exit if the root element was not found.
-                if ( ! sibling ) {
-                        return;
-                }
-
-                // Get the skip-link target's ID, and generate one if it doesn't exist.
-                skipLinkTargetID = skipLinkTarget.id;
-                if ( ! skipLinkTargetID ) {
-                        skipLinkTargetID = 'wp--skip-link--target';
-                        skipLinkTarget.id = skipLinkTargetID;
-                }
-
-                // Create the skip link.
-                skipLink = document.createElement( 'a' );
-                skipLink.classList.add( 'skip-link', 'screen-reader-text' );
-                skipLink.id = 'wp-skip-link';
-                skipLink.href = '#' + skipLinkTargetID;
-                skipLink.innerText = 'Skip to content';
-
-                // Inject the skip link.
-                sibling.parentElement.insertBefore( skipLink, sibling );
-        }() );
-        
-//# sourceURL=wp-block-template-skip-link-js-after
-</script>
 <script id="wp-emoji-settings" type="application/json">
 {"baseUrl":"https://s.w.org/images/core/emoji/17.0.2/72x72/","ext":".png","svgUrl":"https://s.w.org/images/core/emoji/17.0.2/svg/","svgExt":".svg","source":{"concatemoji":"http://localhost:8000/wp-includes/js/wp-emoji-release.min.js?ver=7.0-alpha-61215-src"}}
 </script>

[westonruter]

In 61469:

Themes: Use WP_HTML_Tag_Processor to insert the block template skip link instead of JavaScript.

• The skip link now works when JavaScript is turned off.
• By removing the script, the amount of JavaScript sent to the client is reduced for a very marginal performance improvement.
• A new wp-block-template-skip-link stylesheet is registered, with minification and path data for inlining.
• The CSS for the skip link now has an RTL version generated, although it is not yet served when the styles are inlined. See #61625.
• The wp_enqueue_block_template_skip_link() function now exclusively enqueues the stylesheet since the script is removed.
• For backwards-compatibility, the skip link will continue to be omitted if the_block_template_skip_link() is unhooked from the wp_footer action or wp_enqueue_block_template_skip_link() is unhooked from wp_enqueue_scripts.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10676

Follow-up to [56932], [51003].

Props rutviksavsani, westonruter, dmsnell, whiteshadow01, Slieptsov.
See #59505, #53176.
Fixes #64361.

Thanks @dmsnell for the final review and Thanks @westonruter for taking it over the line with all the necessary checks.