Headings Without a Hierarchy: What the Spec Change Means

The WHATWG Living Standard recently removed its document outline algorithm, officially retiring an idea that browsers never actually implemented. The algorithm existed only in the spec, with a built-in warning against its use. As Bruce Lawson notes, web pages have always had a flat document structure in practice.

This is not exactly breaking news. Adrian Roselli has cautioned about the outline myth since 2013, with his fuller treatment in “There Is No Document Outline Algorithm” still standing as the most complete account of the saga. Amelia Bellamy-Royds has also examined the origins of the problem.

The removal itself is the right move, but it does not erase the considerable effort spent building an algorithm that supported sectioning — nor the years of articles written in anticipation of a feature that never arrived. The real cost is the mental and technical debt left behind by that expectation.

The Missing Generic Heading

Lawson also points to a lingering gap: there is still no generic <h> element that could be placed inside a section and automatically resolve to the correct heading level. In practice, <h1> behaves like an exposed <title>, which becomes constraining when pages are not structured around one article with one top-level heading.

This is a familiar problem in component work. Building a card that logically deserves a low-level heading often means reaching for <h3> even when it feels semantically out of place — and that is before considering the styling adjustments needed when a lower-level heading must visually match a higher one.

Grouping Headings With <hgroup>

Steve Faulkner — who authored the PR that removed the outline algorithm — has a practical guide on using <hgroup> for patterns involving subheadings, subtitles, alternative titles, and taglines. Common markup in the wild often looks like this:

<h1>Disappointingly Average</h1>
<h2>The Autobiography of Geoff Graham</h2>
<h3>by Geoff Graham</h3>

In a flat outline driven by heading levels, that approach breaks down. Each heading would imply a separate section, creating a hierarchy that does not exist:

Disappointingly Average
└── The Autobiography of Geoff Graham
    └── by Geoff Graham

The <hgroup> element offers a better grouping:

When nested within a <hgroup> element, the <p> element’s content represents a subheading, alternative title, or tagline which are not included in the document outline.

That yields a structure like this:

<hgroup>
  <h1>Disappointingly Average</h1>
  <p>The Autobiography of Geoff Graham</p>
  <p>by Geoff Graham</p>
</hgroup>

Currently <hgroup> maps to role=generic, but a proposal is underway to map it to role=group. If adopted, assistive technology would treat those paragraphs as actual subtitles and taglines. Faulkner notes there are obstacles to that change and demonstrates how the pattern can be implemented today with ARIA attributes.

Checking Your Heading Structure

For those revisiting their own outlines in light of the spec change, Matthias Ott offers practical tips on heading structure, along with a list of tools at the end for auditing your heading outline.