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

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), 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 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, 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:

For testing headings in an accessibility-ready WordPress theme, follow the testing procedure with the Theme accessibility guidelines for Headings with meaningful structure.

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