❌

Vue lecture

headingoffset is Not the Document Outline Algorithm

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:

  •  

Don’t Use Fake Bold or Italic in Social Media

I posted something on Mastodon that uses Unicode math symbols to produce fake bold and fake italic text. I used YayText.com to generate it, but I am not linking it because you I don’t want you to use it.

I embedded the post, but you can go to it directly if you prefer.

Then I recorded the screen reader output.

NVDA 2024.4.2 / Firefox 135. Doesn’t announce the fake bold nor fake italic.
JAWS 2025 / Chrome 133. Announces each fake bold and fake italic letter individually, including its case and style.

Those two videos account for ~78% of primary screen reader use. You could stop there and you’d have a good sense of the divergent experience and how it doesn’t match up with the visible text as you might expect.

This is not new information. I was raising this as a concern back in 2018 when Twitter was not yet a Nazi bar.

I know it’s easy to want to blame screen readers. That reflex, however, is a mistake. Instead, as an author you have some responsibility here.

VoiceOver / macOS 15.3.1 / Safari 18.3. Doesn’t announce the fake bold nor fake italic.
Narrator / Windows 11 24H2 / Edge 133. Doesn’t announce the fake bold nor fake italic.

I’m using default settings. Some users will have different settings, but understand screen reader users have the same range of skill & experience with their kit as everyone else has with their own kit.

Try with your built-in screen reader. You have one built into whatever system you are using to read this post (unless you printed it to dead tree pulp, like a boss). If you are unfamiliar with the commands, such as starting it or navigating, I have some screen reader documentation and resources.

VoiceOver / iPadOS 18.3.1 / Safari. Doesn’t announce the fake bold nor fake italic.
TalkBack 15.2 / Chrome 133. Announces the fake bold and fake italic as if it is regular text. TalkBack started doing this in 2021.

I’ve shared six screen reader experiences.

The takeaway should be do not use sites like YayText to make fake bold or italic text (whether on Bluesky, LinkedIn, that Nazi bar, that other Nazi bar, or the yet other Nazi bar, etc.).

If you’re a tester, you may see the speech logs show the characters. These are lies because that doesn’t mean they are announced.

For comparison, this is what it would look like if it was marked up using HTML (and yes, some Masto instances support this) instead of math symbols:

Please do not eat the shrimp scampi in the fridge. It is tasty but will kill you.

All screen readers announce all those words, even if they don’t all expose the bold or italic styling by default.

Now…

Imagine your local government sends this:

Imagine the impact on screen reader users.

Actually, you don’t have to imagine. I recorded the behavior in 2021. It’s not much different today and the examples above will help you guess even if you don’t read that post or try it yourself.

Update: 9 March 2025

This post landed on Hacker News, with the standard mix of comments from people who read the post, mis-read the post, didn’t read the post, think they know “the fix,” know better, and generally debated the nature of their debates.

  •  
❌