❌

Vue normale

headingoffset is Not the Document Outline Algorithm

11 juin 2026 à 23:26

Hi, just me heading off some bad advice I’m starting to see in developer venues.

Background

The JAWS heading list dialog with a yellow three-in-one surface level resting on top and a board nailed over it with hand-scrawled ‘offset=2’.

The proposed Document Outline Algorithm, where headings would automatically reset themselves to the appropriate level based on their position in the DOM structure, was never part of a final HTML specification. It was quickly proven to be unworkable; brief support in JAWS demonstrated that. You can read the tortured history (and a JAWS support demo) in my 2016 post There Is No Document Outline Algorithm.

In 2019 WHATWG worked to resurrect <hgroup>, partly in a novel effort to try to resurrect the Document Outline Algorithm. In the end, even that effort was futile. <hgroup> came back, but it came back as a grouping element only. The only impact it has on heading structures is that browser could, if they really wanted, ignore other headings in the same <hgroup>.

In 2020, Steve Faulkner wrote about the doc-subtitle role, from the Digital Publishing WAI-ARIA Module 1.0, as a way to handle subtitles until <hgroup> found its new footing. Sadly, a cadre of authors thought that role could be the basis for the Document Outline Algorithm.

Authors very much want to make the browser decide heading levels for them. Authors also very much continue to write content and HTML structures that make that impossible.

So I wasn’t surprised when Firefox’s recent announcement of headingoffset support coming to Firefox behind a flag resulted in many cheering the “return” (irony quotes) of the Document Outline Algorithm.

But it isn’t.

headingoffset

The headingoffset attribute lets authors offset heading levels for descendants of a given node.

So if you have, say a dialog that starts at <h2>, you could add headingoffset="2" and then let it pull in (server-side or via your preferred user-slowing front-end tooling) another page that uses <h1> as its first heading, you can be comfortable knowing that <h1> will be treated as <h3> in the accessibility tree.

This can be handy for content re-use without authors needing to make every heading a variable or burning down the DOM each time to forcibly re-write them.

But it’s still the author’s job to make an intentional and good decision. The browser will know nothing more about your content or structure than it did before. And it certainly doesn’t reduce WCAG risk.

Other useful nuggets:

  • headingoffset values must be valid non-negative integers.
  • headingoffset values must be between 0 and 8.
  • headingoffset values greater than 8 are specified to max at level 9, but existing bugs may impact that.
  • Other invalid headingoffset values should fall back to level 2, but again, bugs and implementation decisions wil impact that.
  • headingreset is a boolean attribute that tells 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 browser.

Recap

  1. headingoffset is not the (nor any) Document Outline Algorithm, nor does it replicate it.
  2. headingoffset requires the author to make decisions based on content.
  3. Until JAWS and TalkBack fix existing bugs, probably don’t do / allow any heading levels higher than 6.
  4. Don’t do / allow any heading levels higher than 9.
  5. If you are hoping headingoffset will resolve your heading level problems in a hands-off way with imported or user-generated content, you may end up creating confusion and WCAG risk.
  6. Do not try to use headingoffset to try to recreate the Document Outline Algorithm.

Related

Not a ton of detail in this post, but at 500 words if you want more then here are some resources beyond what I linked:

Brèves d’audit #1 : ratio de contraste d’un lien texte

11 juin 2026 à 08:42
Cas concret d'un audit d'accessibilité numérique : sur quel critère signaler un contraste insuffisant pour le texte d’un bouton ?

Les Sorties Marmots de la Semaine (du 5 au 11 Juin)

Par : Vincent
9 juin 2026 à 07:30

Après une semaine sans aucune sortie Marmots, les affaires reprennent et les jeux qui arrivent sentent bon l’été et les vacances… Les voyages en montgolfière et les barbecues… Les fiestas dans la jungle et les… trucs colorés à assembler. Décidément, certains ont des occupations bizarres en vacances.

Bonne semaine ludique avec vos Marmots !


Panorama

Jules Messaud & Melody Leblond

Melody Leblond

Scorpion Masqué

2 à 4 joueurs

8 ans et plus

Pose de tuiles

Voyagez en montgolfière pour récupérer les meilleures tuiles et former le plus beau des panoramas. Des mécaniques simplissimes, des illustrations toutes choupis et le plaisir simple d’assembler ses tuiles : « Panorama » est un jeu qui invite toute la famille autour de la table, joueurs comme non joueurs…

Le trouver chez

Très Futé Kids 2 : Jungle Party

Wolfgang Warsch

Glen Viljoen

Schmidt

2 à 4 joueurs

6 ans et plus

Roll & Write

« Très Futé Kids » revient pour un nouvel opus. Après avoir préparé un goûter d’anniversaire dans la première boîte, organisez la plus belle fiesta dans la jungle. À votre tour, lancez les dés, choisissez ceux d’une couleur, laissez les autres à vos adversaires, et cochez les meilleurs emplacements pour gagner un maximum d’étoiles colorées.

Le trouver chez

Kumi Kumi

Toshiki Sato

(non crédité)

Miraludo

2 à 4 joueurs

5 ans et plus

Observation/Rapidité

Dans « Kumi Kumi », soyez le plus rapide à reproduire une grille colorée, en combinant et en superposant des tuiles. Celles-ci sont composées de 2 calques de couleurs primaires, et c’est en les superposant que vous obtenez les couleurs secondaires (par exemple : Bleu + Jaune = Vert).

Le trouver chez

Miro Miro

Toru & Aiko Oyama

(non crédité)

Miraludo

2 à 6 joueurs

6 ans et plus

Observation/Estimation

Autre jeu japonais dans la même gamme que « Kumi Kumi », « Miro Miro » est bien plus abstrait abstrait pour les Marmots. Estimez la surface colorée d’une carte référence, en la comparant à toutes celles visibles sur la table. Celui qui choisit la carte qui contient la surface colorée la plus proche remporte la manche.

Le trouver chez

Barbecubes

Brett J. Gilbert & Rob Sparks

Rory Muldoon

Matagot

2 à 6 joueurs

8 ans et plus

Jeu d’adresse

Dans « Barbecubes », vous posez des saucisses et du poisson sur un barbecue. Sauf que les saucisses sont des jetons en pixel art, que le barbecue est fait de buchettes en bois et que c’est avec une petite pince que vous allez tenter de ne rien faire tomber dans les flammes.

Le trouver chez


❌