Page MenuHomePhabricator

[Suggestion] Detect heading levels that don't follow semantic order
Closed, ResolvedPublic

Description

This task involves the work of introducing a new edit suggestion within the VisualEditor Suggestion Mode that makes people aware when heading levels that do not follow semantic order.

Meta

Story

As someone curious to know if there are straightforward and intuitive ways that I might be able to improve the Wikipedia article I was just reading, I'd value knowing if there are any section headings that are out of semantic order, so that I can make the article easier to navigate, especially for people using assistive technologies (like screen readers).

Requirements

  • Card design [i]
    • Title: Heading level
    • Description: Help make this page easier for people to navigate and read by adjusting this heading level. Learn more
      • Note: the Learn more link ought to be configurable on a per project basis.
    • Calls to action:
      • Fix heading: When tapped, automatically adjust the heading in question such that it appears in semantic order
      • Dismiss: When tapped, leave the headings in question unchanged
  • Success state
    • Regardless of what action someone selects, show a toast that reads: Thank you for making it easier for people to navigate and read this page.
  • Detection
    • Present this suggestion when a heading level descends by > 1

i. Please consider this initial card design as preliminary. We will refine the experience together once we have a prototype in-hand.

Event Timeline

Change #1219198 had a related patch set uploaded (by DLynch; author: DLynch):

[mediawiki/extensions/VisualEditor@master] Experimental edit check: skipped heading levels

https://gerrit.wikimedia.org/r/1219198

I've updated the requirements to:

  1. Include the more narrowly-scoped detection logic we converged on offline
  2. Adjust the suggestion card copy and calls to action to better align with "1."

It'd be good to have a non-enwiki page for our default "learn more" link.

CleanShot 2025-12-19 at 18.08.40@2x.png (396×668 px, 40 KB)

This is slightly altered: it's using {{SITENAME}}, doesn't directly refer to articles, and links to https://www.mediawiki.org/wiki/Documentation/Style_guide#Titles_and_headings until overridden.

Also, we've already used "decline" elsewhere -- should we use that instead of "dismiss" here for consistency?

Definitely makes sense to have a universal default, although it does seem like MOS/Accessibility is translated into more languages than MediaWiki's Documentation/Style_guide. Hopefully it'll be possible for each wiki to create a localized destination for the link?

Help make this Wikipedia article

We should avoid using the sitename in message strings as it makes translation harder in languages with cases.

Help make this Wikipedia article easier for people to navigate and read by adjusting this heading level.

  1. Help make this article easier for people to navigate and read by adjusting this heading level.
  2. Help make this page article easier for people to navigate and read by adjusting this heading level.
  3. Help make this easier for people to navigate and read by adjusting this heading level.
  4. Consistent heading levels are easier for people to navigate and read.

("article" is also not guaranteed to be correct -- this check, in particular, is broadly applicable across namespaces.)

Help make this article easier for people to navigate and read by adjusting this heading level.

This looks good to me.

("article" is also not guaranteed to be correct -- this check, in particular, is broadly applicable across namespaces.)

While I agree, to start, we are designing Suggestion Mode for use in the main namespace and accordingly, can refine it later to better accommodate non-NS:0 if/when we see a need to prioritize doing so.

While I agree, to start, we are designing Suggestion Mode for use in the main namespace and accordingly, can refine it later to better accommodate non-NS:0 if/when we see a need to prioritize doing so.

Given that translations are going to happen, it makes more sense to me to start out with a message that'll be correct, since the "article" wording doesn't particularly add anything to this message.

While I agree, to start, we are designing Suggestion Mode for use in the main namespace and accordingly, can refine it later to better accommodate non-NS:0 if/when we see a need to prioritize doing so.

Given that translations are going to happen, it makes more sense to me to start out with a message that'll be correct, since the "article" wording doesn't particularly add anything to this message.

Gotcha. What about, Help make this page easier for people to navigate and read by adjusting this heading level. ?

Sure, that works! Patch is updated with the translation.

@Sdkb
Hopefully it'll be possible for each wiki to create a localized destination for the link?

Yes, it'll just be a matter of overriding the editcheck-tone-descriptionlink message on-wiki.

Change #1219198 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] Experimental edit check: skipped heading levels

https://gerrit.wikimedia.org/r/1219198

Ryasmeen subscribed.

Looks like there are some problems:

empty check dialog:

Screenshot 2026-01-29 at 3.47.04 PM.png (1×2 px, 553 KB)

error in the console:
Screenshot 2026-01-29 at 3.46.20 PM.png (1×2 px, 544 KB)

Screenshot 2026-01-29 at 3.37.02 PM.png (1×2 px, 698 KB)

@Ryasmeen I can't reproduce that at all -- could you perhaps record a video so I can see the exact steps you're taking?

@Ryasmeen I can't reproduce that at all -- could you perhaps record a video so I can see the exact steps you're taking?

I am not seeing those errors today neither the empty check dialog. Instead, I found the Edit Check dialog sometimes not opening at all. Sharing the screen capture for it:

There's definitely something strange going on there. In particular, that "heading level" check that appears at the top at ~7s in which doesn't actually associate with a heading.

For the rest of it, I think it might be the use of empty headings that's making it confused. Let me go dig into that and see if I can find out why.

Change #1236345 had a related patch set uploaded (by DLynch; author: DLynch):

[mediawiki/extensions/VisualEditor@master] EditCheckAction: exact matches on zero-width ranges count as overlaps

https://gerrit.wikimedia.org/r/1236345

Change #1236345 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] EditCheckAction: exact matches on zero-width ranges count as overlaps

https://gerrit.wikimedia.org/r/1236345

There's definitely something strange going on there. In particular, that "heading level" check that appears at the top at ~7s in which doesn't actually associate with a heading.

For the rest of it, I think it might be the use of empty headings that's making it confused. Let me go dig into that and see if I can find out why.

I re-tested this, the extra "heading level" check that was appearing on top is not appearing anymore. However, I noticed, that for some heading level, when we adjust heading level, it is being adjusted to a level where the difference is >1 from the preceding heading level. Sharing a screen capture:


Also, have we changed the button label intentionally from "Fixed Heading" to "Adjust heading level" and the text in the dialog?

I see you starting with wikitext that's approximately:

= Page title =
=== ===
==== ====

You get a level check on === heading. You accept it, and it turns into a == heading (correctly). You accept the second level check, and it looks to me like it moves your cursor down into the empty paragraph below, so I can't see what heading it was turned into.

The first check you accepted also moved your cursor down to the next line, which probably shouldn't be happening. I'll look at that and see whether it's you testing with empty headings again, or whether it's something more general.

Also, have we changed the button label intentionally from "Fixed Heading" to "Adjust heading level" and the text in the dialog?

Yeah, that's the new copy from T415849.

Okay, it's somewhat-inconsistently moving the cursor to the next content offset after the heading after this runs, even when it's not zero-width.

Change #1236869 had a related patch set uploaded (by DLynch; author: DLynch):

[mediawiki/extensions/VisualEditor@master] HeadingLevels check: explicitly set a selection when done

https://gerrit.wikimedia.org/r/1236869

Change #1236869 merged by jenkins-bot:

[mediawiki/extensions/VisualEditor@master] HeadingLevels check: explicitly set a selection when done

https://gerrit.wikimedia.org/r/1236869

Ryasmeen edited projects, added Verified; removed Editing QA.