Firefox's headingoffset Is Not the Document Outline Algorithm

The proposed Document Outline Algorithm — where headings would automatically reset their level based on DOM position — never shipped in a final HTML specification. Brief support in JAWS proved the idea unworkable back in 2016. Yet Firefox's announcement of headingoffset support, currently behind a flag, has developers cheering what they call its "return." It isn't one. And the distinction matters for anyone who touches WCAG conformance.

The warning comes from a veteran accessibility practitioner who has tracked this saga for a decade, starting with the 2016 post There Is No Document Outline Algorithm, which documents the algorithm's tortured history and includes a JAWS support demo.

What actually changed in the spec's history?

In 2019, WHATWG resurrected <hgroup> partly in an attempt to revive the outline algorithm. That effort failed too. <hgroup> returned as a grouping element only. Its sole effect on heading structure: browsers could, if they chose, ignore other headings inside the same <hgroup>, per the HTML Accessibility API Mappings 1.0.

Then in 2020, Steve Faulkner wrote about doc-subtitle — a role from the Digital Publishing WAI-ARIA Module 1.0 — as a stopgap for subtitles. A cadre of authors decided that role could underpin the outline algorithm. Wrong again.

The pattern repeats. Authors want browsers to decide heading levels for them. Authors also keep writing content and HTML structures that make that impossible. Both statements can be true. Neither is new.

What does headingoffset actually do?

The attribute lets authors offset heading levels for descendants of a given node. Concrete example: a dialog starting at <h2> gets headingoffset="2", and when it pulls in another page whose first heading is <h1> — server-side or via your preferred user-slowing front-end tooling — that <h1> is treated as <h3> in the accessibility tree.

That's handy for content re-use. No heading variables. No burning down the DOM to rewrite levels each time. But the browser still knows nothing more about your content or structure than it did before.

"It's still the author's job to make an intentional and good decision. And it certainly doesn't reduce WCAG risk."

The fine print matters:

• Values must be valid non-negative integers.
• Values must sit between 0 and 8.
• Values above 8 are specified to max at level 9, but existing bugs may break that.
• Invalid values should fall back to level 2 — bugs and implementation decisions will interfere.
• headingreset is a boolean attribute telling browsers to ignore headingoffset for that node and its descendants.
• Do not use headingoffset until you can confirm support for the computed heading level in your target audience's browser.

Where is the WCAG risk?

The author's recap is blunt. headingoffset is not the Document Outline Algorithm, nor does it replicate it. It requires the author to make decisions based on content — the opposite of hands-off.

Until JAWS and TalkBack fix existing bugs, probably don't do or allow any heading levels higher than 6. Don't go above 9 at all. And if you hoped headingoffset would solve heading-level problems with imported or user-generated content automatically, you may instead create what TPGi calls "heading-off confusion" — a documented path to WCAG failure.

One comparison grounds the stakes: an <h1> silently renumbered to <h3> is convenient for the author and invisible to the user until a screen-reader heading list stops making sense.

The author closes with related reading spanning 2016 to Manuel Matuzović's Context-aware headings in HTML of 3 June 2026. Until JAWS and TalkBack clear their heading-level bug backlog, headingoffset remains a tool for disciplined authors, not a shortcut for everyone else.