Document the auto addition of skip links on Block Themes #1677
Labels
developer documentation (DevHub)
Improvements or additions to developer documentation
new document
Requests for new page/article.
[Status] To do
Issue marked as Todo
themes
Issues for Theme Developer Handbook
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 amain
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.
The text was updated successfully, but these errors were encountered: