Document the auto addition of skip links on Block Themes

[matiasbenedetto]

What is the new page you are requesting?

A new page or section is required in the Theme Handbook. There's an undocumented feature or technique around adding skip links in block themes.

Starting in WordPress 6.4, skip links are automatically added to the pages rendered in sites using block templates.

This is the core code in charge of making this functionality work: https://github.com/WordPress/wordpress-develop/blob/5f8f3789d16e28923772f1675e371baaea3e71ec/src/wp-includes/theme-templates.php#L101-L220

How will this new page help you?

The auto addition of the skip link in block templates requires an HTML <main> tag in the template; otherwise, the skip link isn't added. This doesn't seem to be documented. We need to explain how this works. The only explanation I found is how to add the skip link manually, probably only helpful for classic themes: https://make.wordpress.org/accessibility/handbook/markup/skip-links/

The WordPress theme directory requires that the themes have a skip link working, and it's a good accessibility practice.

Proposal for the section or page content:

The new page or section in the block themes handbook could look similar to the following. Feel free to add and change whatever you think is needed:

---

What is a Skip Link?

A skip link is an HTML link element (<a>) that directs users to the main content of a page, often hidden from immediate view. This link is an accessibility feature designed to help users who rely on screen readers or keyboard navigation.

Why Are Skip Links Needed?

Web pages often contain navigation menus, search bars, and other elements before the main content. For users navigating with keyboards or screen readers, moving through all these elements repeatedly can take time and effort. Skip links (also known as "skip to content" links) allow these users to bypass unnecessary elements and jump directly to the main content, improving their browsing experience.

How to Implement Skip Links in Block Themes

Starting with WordPress 6.4, skip links are automatically added to pages on sites using block templates. To enable this functionality, include a <main> tag that contains your page's primary content within your templates. You can easily achieve this using the WordPress editor. Add a Group block for your template's main content or modify an existing block to render as a main HTML element.

A video showing how to add the main tag to a template:

Screencast from 08-07-24 18_37_54.webm

---

@WordPress/block-themes I'd appreciate your input.

[github-actions[bot]]

Heads up @WordPress/docs-issues-coordinators, we have a new issue open. Time to use 'em labels.

[mikachan]

Thanks for working on this! I agree that this should be documented in the theme handbook. Your text reads really well to me 👍

cc @WordPress/block-themers

[github-actions[bot]]

Heads up @kafleg @carolinan @TeBenachi - the "themes" label was applied to this issue.

[carolinan]

The accessibility chapter or section in the theme developer handbook still needs a volunteer to write it. Tracked here: https://github.com/WordPress/Documentation-Issue-Tracker/issues/816

[luminuu]

Starting with WordPress 6.4, skip links are automatically added to pages on sites using block templates.

I'd rephrase this, as it only works automatically, when a main tag is present. The default themes do have it I think, but many many block themes don't, as there's only a handful of block themes that have the accessibility-ready tag.

I'll give it a try:

Starting with WordPress 6.4, skip links are automatically added to pages on sites using block templates, if a <main> tag is found in the template. If the template doesn't include a <main> tag, find the block that contains your page's primary content within your templates. If it's already in a Group block, you can assign the <main> tag to that Group block. If not, add a Group block that holds your primary content.