wpaccessibility · rianrietveld · Apr 1, 2026
diff --git a/docs/topics/code/heading-structure/index.md b/docs/topics/code/heading-structure/index.md
@@ -2,7 +2,7 @@
 title: Heading structure
 layout: default
 parent: Frontend code
-description: How to use headings in your content in an accessible way.
+description: How to use headings in theme development in an accessible way.
 nav_order: 3
 ---
 
@@ -12,44 +12,74 @@ Headings are the backbone of your content structure and describe the content on
 
 Visually, it only matters that these are set off in design. Using appropriate heading levels is the screen reader equivalent of good visual design: if headings are not present, then all the text is undifferentiated – if headings are used inappropriately, then content doesn’t make sense.
 
-## Rules of thumb for headings in theme development:
+{: .info .callout }
+How to use headings in the editor is addressed in the “Content and images” section [Using headings in content]({{site.baseurl}}/docs/topics/content/headings/).
+
+## Rules of thumb for headings in theme development
 
 - One unique H1 per page, post or archive that describes the primary topic of the page. In most themes, this is the post -, page – or archive title.
 - Use H2 through H6 to divide major sections of the page, such as widget areas, comment sections, or other major segments of the page.
 - Use headings in a logical and hierarchical structure.
-
-Use HTML headings to meaningfully describe the content that follows, not as a design element. A heading means “this text describes the information that follows it.” There should not be text before the heading that is part of what that heading describes, and there must be content following the heading.
+- Do not skip a heading level. 
+- Use headings to meaningfully describe the content that follows, not as a design element.
 
 {: .callout .info }
 **Note**: If you use a headings validation tool, a warning may pop up when the first heading is not an H1. This only applies when your web page needs to comply with WCAG 2 AAA (triple A). The global web standard is WCAG 2 AA (double A) and starting with an H2 (for e.g. the navigation) is allowed at the AA standard.
 
+WPBeginner published a practical guide on headings for WordPress: [How to Properly Use Heading Tags in WordPress (H1-H6 Explained)](https://wp-coder.net/blog/how-to-properly-use-heading-tags-in-wordpress-explained/), also addressing the impact of a good heading structure on SEO.
+
+### Sections and headings
+
+The practice to use an H1 for each `<section>` is outdated and harming accessibility, as multiple H1s don't give structure to the content. If everything is an H1, there is no indication about what the main content is about. Read more about this on [Computer says NO to HTML5 document outline](http://html5doctor.com/computer-says-no-to-html5-document-outline/) by Steve Faulkner.
+
+If you want to give a section an [accessible name]({{site.baseurl}}/docs/topics/code/accessible-name/), use `aria-labelledby`, linking the heading to the section. For example:
+```html
+<section aria-labelledby="news-heading">
+  <h2 id="news-heading">The latest news</h2>
+    [...]
+</section>
+```
+
+### Heading levels in components, it depends
+
+Take extra care when including a heading in a component or block. The heading level may depend on the way or location a component is included in the page. 
+
+Make it possible to change a heading level, depending on the semantics of the heading structure on that specific web page. A widget may need a different heading level in the sidebar than when it's used in the content.
+
+## How to test for a proper heading structure
+
+Use the browser tool **HeadingsMap** to test the heading structure of an entire web page:
+- [Headings Map toolbar for Edge](https://microsoftedge.microsoft.com/addons/detail/headingsmap/bokekiiaddinealohkmhjcgfanndmcgo)
+- [Headings Map toolbar for Chrome](https://chrome.google.com/webstore/detail/headingsmap/flbjommegcjonpdmenkdiocclhjacmbi?hl=en)
+- [Headings Map toolbar for Firefox](https://addons.mozilla.org/en-US/firefox/addon/headingsmap/)
+
+For testing headings in an accessibility-ready WordPress theme, follow the testing procedure with the Theme accessibility guidelines for [Headings with meaningful structure]({{site.baseurl}}/docs/topics/theme-guidelines/headings-structure/).
+
 ## Resources
 
-### Testing tools for headings
+### WCAG Success Criteria for the heading structure
+
+Using a meaningful heading structure is necessary to meet the WCAG success criteria:
+
+- [WCAG 1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/quickref/#info-and-relationships) (Level A).
+- [WCAG 2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG22/quickref/#headings-and-labels) (Level AA).
+- [WCAG 2.4.10 Section Headings](https://www.w3.org/WAI/WCAG22/quickref/#section-headings) (**Level AAA**).
 
-- [WAVE](http://wave.webaim.org/extension/)
-- [Headings map for Chrome](https://chrome.google.com/webstore/detail/headingsmap/flbjommegcjonpdmenkdiocclhjacmbi?hl=en)
-- [a11yTools Extension for Safari macOS](http://www.pauljadam.com/extension.html)
-- [Tota11y](http://khan.github.io/tota11y/)
+### Other resources
 
-### Heading semantics
+#### Heading structure in WordPress
 
-- [Semantic Structure on WebAIM](https://webaim.org/techniques/semanticstructure/)
-- [The HTML5 Document Outline](https://developer.paciellogroup.com/blog/2013/10/html5-document-outline/)
-- [Heading Tags (H1, H2, H3, P) in HTML](http://accessibility.psu.edu/headingshtml/)
-- [Computer says NO to HTML5 document outline](http://html5doctor.com/computer-says-no-to-html5-document-outline/)
+- [How to Properly Use Heading Tags in WordPress (H1-H6 Explained)](https://www.wpbeginner.com/wp-tutorials/how-to-properly-use-heading-tags-in-wordpress-explained/) by WPBeginner.
+- [The Heading Block](https://wordpress.org/documentation/article/heading-block/) on WordPress.org
 
-### Heading structure best practices
+#### Resources on heading semantics
 
-- [Web Accessibility Tutorials: Headings](https://www.w3.org/WAI/tutorials/page-structure/headings/)
-- [Web Accessibility Tutorials: Labeling Regions](https://www.w3.org/WAI/tutorials/page-structure/labels/#using-aria-labelledby)
-- [Web Page Mistakes: Heading Structure – Heading Tag](http://www.webpagemistakes.ca/heading-structure-heading-tag/)
-- [Nomensa: How to structure headings for web accessibility](https://www.nomensa.com/blog/2017/how-structure-headings-web-accessibility)
-- [Using headings to improve accessibility (Drupal)](https://www.drupal.org/docs/7/creating-accessible-themes/using-headings-to-improve-accessibility). Note class=”element-invisible” is in WP class=”screen-reader-text”
-- [MRW web: H1 Headings Are Important](https://mrwweb.com/use-html-headings-for-accessibility/)
-- [MRW web: Common heading-mistakes](https://mrwweb.com/common-heading-mistakes/)
+- [Semantic Structure on WebAIM](https://webaim.org/techniques/semanticstructure/), by WebAIM.
+- [Web Accessibility Tutorials: Headings](https://www.w3.org/WAI/tutorials/page-structure/headings/), by the W3C.
+- [The HTML5 Document Outline](https://developer.paciellogroup.com/blog/2013/10/html5-document-outline/) by Steven Faulkner. 
+- [Accessible heading structure](https://www.a11yproject.com/posts/how-to-accessible-heading-structure/) by Rian Rietveld on the A11y Project.
 
-### Heading structure in WordPress
+#### Heading structure best practices
 
-- [The Headings Hierarchy Challenge](https://www.joedolson.com/2014/11/headings-hierarchy-problem/)
-- [Accessible HTML5 heading structure in WordPress](http://rianrietveld.com/2014/11/21/html5-headings-in-wordpress-lets-fight/)
+- [Web Accessibility Tutorials: Labeling Regions](https://www.w3.org/WAI/tutorials/page-structure/labels/#using-aria-labelledby), by the W3C.
+- [MRW web: Common heading-mistakes](https://mrwweb.com/common-heading-mistakes/), by Mark Root-Wiley.
diff --git a/docs/topics/content/headings.md b/docs/topics/content/headings.md
diff --git a/docs/topics/content/headings/index.md b/docs/topics/content/headings/index.md
@@ -0,0 +1,96 @@
+---
+title: Headings
+layout: default
+parent: Content and images
+description: A heading should simply and concisely describe the content that follows.
+nav_order: 3
+---
+
+# Using headings in the content
+
+## What are headings?
+
+Headings are the framework of your content. A good heading should simply and concisely describe the content that follows.
+
+The heading level is important. The H1 (heading level 1) is reserved for the post or page title. For most themes that is the title you give a page or post. Use heading level 2, 3 and 4 to divide your content into meaningful sections, like the index of a book.
+
+Choose heading levels by meaning, not by visible size. This way artificial intelligents (AI), search engines and screen readers (software used by your blind visitors) understand the structure and meaning of the content better. 
+
+{: .info .callout }
+How to implement headings in development is addressed in the “Frontend code” section [Heading structure in theme development]({{site.baseurl}}/docs/topics/code/heading-structure/).
+
+### Best practices for headings summarized
+
+- The H1 (heading level 1) is reserved for the post or page title.
+- Use the other headings to divide content into scannable blocks.
+- Headings to describe the content below. Do not use a heading just to make the text appear bigger or stand out.
+- Don't skip a heading level from the top down.
+- Use a real heading instead of making text only bold or large.
+
+A heading means “this text describes the information that follows it.” There should not be text before the heading that is part of what that heading describes, and there must be content following the heading.
+
+{: .tip .callout }
+**Tip:** If you don’t like the sizes of the headings in your content, you should adjust the design of the heading rather than selecting a different heading level. This helps with accessibility as well as with content adaptability. Selecting a heading based on size might make a change of theme more difficult.
+
+## Examples of heading structures
+
+Your page’s headings might resemble a structure similar to this one on a complex page:
+
+```text
+Heading 1 (post title)
+    Heading 2 (major section)
+        Heading 3 (subsection)
+    Heading 2 (additional major section)
+        Heading 3
+            Heading 4
+        Heading 3
+            Heading 4
+    Heading 2
+        Heading 3 (post sub-heading)
+        Heading 3 (post sub-heading)
+ ```
+
+If we use this post as an example, the heading structure for the content looks like this:
+
+```text
+    Heading 1: Using Headings in Content (main post topic)
+        Heading 2: What are headings? (subsection)
+            Heading 3: Best practices for headings summarized
+        Heading 2: Examples of heading structures (subsection)
+        Heading 2: How to test for a proper heading structure (subsection)
+        Heading 2: Resources (subsection)
+            Heading 3: WCAG Success Criteria for the heading structure
+            heading 3: Other resources
+```
+
+## How to test for a proper heading structure
+
+In WordPress, you can check the heading structure in the  "Outline" tab. The outline tab is visible after clicking the button "Document Overview" in the top bar of the editor.
+
+![Screenshot of the document outline of the page get started at a contributor day]({{site.baseurl}}/assets/images/document-outline.png)
+
+Use the browser tool **HeadingsMap** to test the heading structure of an entire web page:
+- [Headings Map toolbar for Edge](https://microsoftedge.microsoft.com/addons/detail/headingsmap/bokekiiaddinealohkmhjcgfanndmcgo)
+- [Headings Map toolbar for Chrome](https://chrome.google.com/webstore/detail/headingsmap/flbjommegcjonpdmenkdiocclhjacmbi?hl=en)
+- [Headings Map toolbar for Firefox](https://addons.mozilla.org/en-US/firefox/addon/headingsmap/)
+
+{: .callout .info }
+**Note**: If you use a headings validation tool, a warning may pop up when the first heading is not an H1. This only applies when your web page needs to comply with WCAG 2 AAA (triple A). The global web standard is WCAG 2 AA (double A) and starting with an H2 (for e.g. the navigation) is allowed at the AA standard.
+
+## Resources
+
+### WCAG Success Criteria for the heading structure
+
+Using a meaningful heading structure is necessary to meet the WCAG success criteria:
+
+- [WCAG 1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/quickref/#info-and-relationships) (Level A).
+- [WCAG 2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG22/quickref/#headings-and-labels) (Level AA).
+- [WCAG 2.4.10 Section Headings](https://www.w3.org/WAI/WCAG22/quickref/#section-headings) (**Level AAA**).
+
+### Other resources
+
+- [How to Properly Use Heading Tags in WordPress (H1-H6 Explained)](https://www.wpbeginner.com/wp-tutorials/how-to-properly-use-heading-tags-in-wordpress-explained/) by WPBeginner.
+- [Accessible heading structure](https://www.a11yproject.com/posts/how-to-accessible-heading-structure/) by Rian Rietveld on the A11y Project.
+- [Headings and why you should use them](https://yoast.com/headings-use/) by Brendan Reid on Yoast.
+
+