Heading structure in theme development

Headings are the backbone of your content structure and describe the content on a webpage. Good headings also make the site easier to scan. Sighted users are accustomed to seeing sections of content broken up using various font sizes that highlight groups of related content.

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.

How to use headings in the editor is addressed in the “Content and images” section Using headings in content.

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.
  • Don’t skip a heading level from the top down.
  • Use headings to meaningfully describe the content that follows, not as a design element.

WPBeginner published a practical guide on headings for WordPress: How to Properly Use Heading Tags in WordPress (H1-H6 Explained). The guide also addresses the impact of a good heading structure on SEO.

Sections and headings

The obsolete practice of using an H1 for each <section> harms accessibility, as the algorithm to structure the document outline was never implemented. If everything is an H1, there is no indication about what the main content is about. Read more about this in Computer says NO to HTML5 document outline by Steve Faulkner.

If you want to give a section an accessible name, use aria-labelledby, linking the heading to the section. For example:

<section aria-labelledby="news-heading">
  <h2 id="news-heading">The latest news</h2>
    [...]
</section>

Heading levels in components depend on context

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 based 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:

Are you testing the heading structure for an accessibility-ready WordPress theme? Please follow the testing procedure outlined in the Theme Accessibility Guidelines under Headings with meaningful structure.

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 (such as in 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:

Other resources

Heading structure in WordPress

Resources on heading semantics

Heading structure best practices

Read how to contribute to this documentation.