In T13555#1809690, @Graham87 wrote:

Screen reader users like myself would want the "edit" term read out, so we can edit each section like everybody else. The media attribute isn't supported well by screen readers anyway. I for one would just like the old behaviour (pre-2006) where the edit link is outside the section name.

Preferences are OK; the more choices & the more options available to the User, the better the Wiki experience can be, but this should never be achieved by placing 'an overbearing cost' upon other User's preferences or needs (whenever possible).

That said.. what is currently your experience with headings and screen-readers?

It sounds like the current state of affairs for you is indeed "reading out" all the "text" being "detected" but for some reason you are unable to actually invoke an edit session as you once were able to prior to the ~2007 change?

The whole point I'm trying to make here is why not try to make both possibilities a "reality" that's also "easy" all around if possible? See the semi-relevant points made in T33932 for example.

@Graham87, I applied some screen-reader specific .css to the test2.wikipedia.org test site.

Can you tell us if the [Edit] links are still being displayed and work to open an edit session but are no longer "read aloud" with your screen reader now?

Try https://test2.wikipedia.org/wiki/Headings for starters or you can make your own testbed to check against.

@GOIII: The headings on that page read exactly the same as they do on the regular site on the latest release versions of both JAWS and NVDA.

In T13555#1809839, @GOIII wrote:

That said.. what is currently your experience with headings and screen-readers?

It sounds like the current state of affairs for you is indeed "reading out" all the "text" being "detected" but for some reason you are unable to actually invoke an edit session as you once were able to prior to the ~2007 change?

Oops, I missed this comment until now. The English and German Wikipedias (and perhaps others?) use a JavaScript trick to put the edit link *after* the section name, so when I navigate by heading I hear "<heading name> edit". I can access the section editing link fine; it's just annoying to hear the word "edit" after each section name.

In T13555#1811100, @Graham87 wrote:

Oops, I missed this comment until now. The English and German Wikipedias (and perhaps others?) use a JavaScript trick to put the edit link *after* the section name, so when I navigate by heading I hear "<heading name> edit". I can access the section editing link fine; it's just annoying to hear the word "edit" after each section name.

Javascript trick? Even when I'm not logged in, the edit link is ~1em to the right of the section heading. Its been some time since the Edit link loaded at the far right of the section heading (unless there some difference in the skin being used or something.

Anyway if you can double check that javascript thing and re-check the test page from earlier once again (I tweaked it some more), I'll stop pestering you and go dig up a screen reader of my own to look into this aspect on my own.

Thanks again

In T13555#1812616, @GOIII wrote:

Javascript trick? Even when I'm not logged in, the edit link is ~1em to the right of the section heading. Its been some time since the Edit link loaded at the far right of the section heading (unless there some difference in the skin being used or something.

Anyway if you can double check that javascript thing and re-check the test page from earlier once again (I tweaked it some more), I'll stop pestering you and go dig up a screen reader of my own to look into this aspect on my own.

Thanks again

I don't know how it was done ... but I seem to recall the position of the section edit links was changed some time ago.

I've checked the test page again; still no change.

In T13555#1812843, @Graham87 wrote:

I don't know how it was done ... but I seem to recall the position of the section edit links was changed some time ago.

Well "in the beginning", the default rendering of the [Edit] link was at the very-most far right of the section heading and at some point later on they had it display immediate after the section heading with approx. 1.00em spacing in between the two.

I believe the default positioning of the html element 'holding' that auto [Edit] link generation has gone once or twice from being 'placed' before then and/or after the H# tag and/or currently to within the H# tag itself -- switching from DIV to SPAN tags (and back) accordingly.

So the positioning of the element tags within the html document outline didn't necessarily correlate to the change in the rendering of the [Edit] link; the two aspects are associated but independent of each other. In your case, however, once the positioning of the link was placed within the H# tags, it seems to have affected your screen reader's behavior.

I've checked the test page again; still no change.

Damn that's odd. There is no reason for those settings failing to prevent the reading aloud of Edit. The last thing I can think of trying is "setting" the volume for that containing element to 'zero' but that's sort of hackish; so I'd rather not. I'm curious to hear what happens if you switch to Mobile-mode where the [[Edit]] link becomes a pencil icon. Either way, if I come across anything worth trying, I'll touch-back with it here.

In the mobile version, the edit links are still read out when navigating by heading here.

One thing related, noticed in conversation with screenreader user browsing a desktop article of Finish Wikipedia, the brackets are read out every time as well. They are IMO only (somewhat) useful for visual users, exposing them in a screenreader seems verbose to me, as the link gets read out anyways separate object. The divider, as of current <span class="mw-editsection-divider"> | </span>, might make sense, but even that is debatable.

We could consider adding aria-hidden="true" to the brackets. Posting here, as this is mainly related to the edit links experience, but happy to carve the topic out in a separate task.

In T13555#6474274, @Volker_E wrote:

One thing related, noticed in conversation with screenreader user browsing a desktop article of Finish Wikipedia, the brackets are read out every time as well. [snip]

We could consider adding aria-hidden="true" to the brackets. .... but happy to carve the topic out in a separate task.

Yeah, maybe better to have a separate task for that.

I would guess the brackets being in the HTML is something for older browsers that may be unsupported now. Is there a reason those couldn't be moved to CSS ::before and ::after instead pending some ultimate resolution to this task?

Timeless display: nones the brackets in favor of CSS adding a little pen icon on .mw-editsection. I don't really see how Minerva is adding the icon but it also has no brackets though? I don't see an HTML img and I don't see the CSS for background-image (Javascript-added image?).

Yeah, maybe better to have a separate task for that.

T268900: Clean up section edit link brackets

I've reread this task (and many related ones) and everyone agrees on the general structure, from @TheDJ in 2013 (T13555#167239) to @bwang today (T13555#8256567).

The patch itself for this is easy enough to write (but note that, due to HTML caching, we need to ensure that both old and new HTML is compatible with both the old and new CSS/JS). The problem is compatibility with everything that depends on the current markup – at least MobileFrontend and DiscussionTools will need to be updated. There may also be gadgets affected that I don't know about; whoever works on this should prepare a documentation page for gadget authors like https://meta.wikimedia.org/wiki/Change_to_section_edit_links.

I can't promise resolving this task, but it seems that we will be working on something similar for DiscussionTools-enhanced headings on talk pages (T314714). Our current implementation has the same issue as this, but we're adding more content than just [edit] links, making the problem much worse. I am thinking that we should use the same markup there as what was proposed here, which should make future changes less painful, since we'll have to at least update MobileFrontend, and maybe also discover and update other extensions and gadgets that would be affected, while causing less breakage that the change for all headings on all pages would cause.

There are some details to consider:

• <header> or <div>? This seems like the perfect use case for <header>, but no one knows how screen readers will treat it, so <div> seems like the safe option until someone proves that <header> would be helpful.
• Where to put the id attribute? Task T33932 requests that it should go on the outermost wrapper of headings, and this would be a good opportunity to change this. There are also extra <span id="…"> nodes with fallback IDs for IDs that need percent-encoding, currently placed inside the <h2> (T152540).

…and also a few follow-up ideas worth noting:

• If additional links are added next to [edit], where should they go?
  • VisualEditor's [edit source] are inside <span class="mw-editsection">
  • DiscussionTools' [subscribe] are before <span class="mw-headline"> (T313406)
  • Proposed [share] links could go after <span class="mw-editsection"> or before <span class="mw-headline"> (T18691)
• If additional content related to the heading is added, where should it go?
  • MobileFrontend's expand/collapse icon is currently inside <h2> before everything else; presumably it would go inside the <div>/<header> wrapper after these changes
  • DiscussionTools' metadata are currently inside <h2> after everything else; presumably they would go inside the <div>/<header> wrapper after these changes (T314714)
• When we switch to Parsoid HTML, section edit links will need to be added to it as well, and we should make it easy to use the exact same markup there (T269630). Also, Parsoid HTML will have <section> wrappers around each heading and its section, and we should avoid anything that would break this (T8104). MobileFrontend currently has <section> wrappers after the heading, for top-level headings only.

@bwang this task came up in the editing team / web team sync and we'd ideally like this to be included as part of the Q2 goal around accessibility so I've added this as a subtask. Could you sync with Bartosz to better understand this issue if needed and if it is inline with the other work we have planned?

The editing team would consider this a blocker for their usability improvements being deployed on bigger wikis, so in terms of timeline they would need this by end of November.

@Jdlrobson This is definitely a high impact accessibility task so I think it would be great if we included this as part of our Q2 goal. Just to note, the other Q2 accessibility tasks focus on Desktop Improvements related UI, while this impacts legacy and modern Vector.

Thanks @matmarex for following up on this, regarding your questions:

• I feel <div> is safer than <header> given inconsistencies with how browsers/screenreader combos read out the <header> (i.e. this Safari bug filed by @TheDJ). If we discover <header> is better, it shouldnt be as hard to switch it out later on.
• I agree the id should go on the heading element rather than the span. Personally, I think it even makes sense to remove the span altogether, as they seem mostly needed to make the links inline inside the heading element.

So the markup could look like this

<div>
  <h3 id="Subheading_1.1" class="mw-headline">
    Subheading 1.1
  </h3>
  <div class="mw-editsection">...</div>
  <!-- Additional elements can go here or inside .mw-editsection -->
</div>

With this markup it would make sense to use display: flex, which essentially aligns Vector's heading styles with Minerva. At that point I think it might make sense to update core styles to make these styles the default. Flex display would also impact DiscussionTools at the minimum, which inserts the [subscribe] link before .mw-headline.

I tried implementing the ideas above and seeing what breaks.

I realized that, in order to preserve current skin styles for different headings, the outermost wrapper <div> will need to have classes (or attributes) that identify the heading level, i.e. something like <div class="mw-heading2"><h2>…</h2></div>. This is needed e.g. for Vector's full-width underline below the level 1 and 2 headings. (It might be possible to implement those styles without that, but we'd need to do something clever like absolutely positioned pseudo-elements to draw that underline, and I wouldn't wish it on anyone to maintain that code.)

Also, I think we will need to support styling headings without the outermost wrapper <div>, not just during the migration, but for the foreseeable future (only styling though, not collapsing in MobileFrontend and whatever DiscussionTools does). There are many special pages that display headings using plain HTML <h2> markup, and I think it's reasonable to still support that. It would also avoid tricky changes in VisualEditor, which uses plain HTML <h2> etc. on the editing surface. This complicates the CSS somewhat (need to apply styles to h2, .mw-heading2 and then cancel them out on .mw-heading2 h2).

You can find my experiments at https://gerrit.wikimedia.org/r/q/topic:heading-markup-T13555 (VERY NOT FINAL) and a demo at https://patchdemo.wmflabs.org/wikis/92a85d2cdd/wiki/Special:HeadingTest.

Proposed markup is, more-or-less:

<section>
 <div class="heading-stuff">
  <h2>Heading</h2>
  <div>[edit] (etc)</div>
 </div>
 <div class="content-stuff">
  Lorem ipsum...
 </div>
 <section>
    ... nested section...
 </section>
</section>

@matmarex is proposing .header-stuff and I'm countering with .content-stuff (since that lets us do section collapsing in CSS, which has been a very frequent request) but maybe we "need" both. There are CSS tricks like using section > * to target the content and overriding that with section:first-child for the heading, but those tricks get very fragile.

Currently Parsoid emits the <section> tag, but not any of the section edit stuff. Visual Editor then strips the <section> tags (as well as some ID attributes inside the headings) when it loads. The problem with continuing this approach, however, is that if the above HTML structure becomes canonical for read views, we can expect site CSS to target it in ways that will be very difficult to reproduce when VE leads. That is, the layout of the headings and content sections will "flash" and "look wrong" when VE loads. So I think it would be better for VE to try to preserve the <section> and <div> wrappers (if we decide to add these), even though that adds some complexity to VE to manage cursor state in contenteditable around these invisible elements etc.

Strawdog proposal is to prototype the above markup in Discussion Tools, which is using Parsoid read views "soon" and so can be an early-adopter of <section> tags in read view. Then this markup can be rolled out to main article pages along with the rest of the Parsoid read view changes. We'll still have to eventually have VE handle this in a reasonable way to avoid content 'flash' on load, but since DiscussionTools doesn't edit the entire page at once this doesn't have to be done immediately.

Drive-by comment: I'd make the wrapper around edit a span, not a div. We currently feature classes on the links, we should also feature classes on the wrapper element.

@cscott Would it be more appropriate for the <section> change to be handled in another task? As I understand this task is focused on the heading and the heading's container, I'm worried adding the <section> would increase the scope of this work or cause more regressions

In T13555#8327783, @Volker_E wrote:

Drive-by comment: I'd make the wrapper around edit a span, not a div. We currently feature classes on the links, we should also feature classes on the wrapper element.

@Volker_E Are you suggesting using a <span> in order to style the links as inline elements? Considering the other types of elements that could go inside the container (i.e. subscribe links, proposed share link), I was initially thinking it would be more flexible to use <div> elements and flexbox in order to get the elements to be inline, and have the most flexibility for other content

Change 857772 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/extensions/MobileFrontend@master] Compatibility with new heading structure

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

Change 842860 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/skins/Vector@master] Add styles for new heading structure

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

Change 857770 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/skins/Timeless@master] Add styles for new heading structure

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

Change 857769 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/skins/Nostalgia@master] Add styles for new heading structure

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

Change 857768 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/skins/Modern@master] Add styles for new heading structure

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

Change 857767 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/skins/MinervaNeue@master] Add styles for new heading structure

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

Change 857766 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/skins/CologneBlue@master] Add styles for new heading structure

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

Change 859139 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/extensions/VisualEditor@master] Compatibility with new heading structure

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

Change 842937 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/extensions/DiscussionTools@master] Compatibility with new heading structure

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

Change 842859 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/core@master] Move section edit links outside headings (new heading structure)

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

That's a lot of patches. Here's a human-readable summary: (edit: see new version below)

Wow, that's a huge amount of work already @matmarex, well done !

Change 860553 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/extensions/PageImages@master] Compatibility with new heading structure

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

Change 860555 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/extensions/Scribunto@master] Compatibility with new heading structure

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

Change 860577 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/extensions/LabeledSectionTransclusion@master] Compatibility with new heading HTML

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

Change 860582 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/skins/MinervaNeue@master] Compatibility with new heading HTML

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

Change 860583 had a related patch set uploaded (by Bartosz Dziewoński; author: Bartosz Dziewoński):

[mediawiki/skins/Vector@master] Compatibility with new heading HTML

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

That's a lot of patches. Here's a human-readable summary: (version 2, since I missed a few things)

Preparatory work:
(Fixing issues I discovered in various places while working on these changes, which I decided to resolve first because they either made it more difficult to make the changes, or made it more difficult to verify their correctness)

• T314714: Metadata and buttons should be inserted after a heading, not inside of it
• T323773: Remove unnecessary uses of <span class="mw-headline">
• https://gerrit.wikimedia.org/r/c/mediawiki/core/+/857542
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/Timeless/+/859133
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/MinervaNeue/+/860051
• https://gerrit.wikimedia.org/r/c/mediawiki/extensions/MobileFrontend/+/851166

Documentation page for developers:
(It may be helpful to read this first before reviewing the code, it explains some of the changes)

• https://www.mediawiki.org/wiki/Heading_structure_changes

MediaWiki core patches:

• https://gerrit.wikimedia.org/r/c/mediawiki/core/+/842859

Skin patches that only update the styles: [Can be merged before core]
(I have tested WMF-deployed skins and the Example skin. Third-party skins may need updates, see the documentation page for details.)

• https://gerrit.wikimedia.org/r/c/mediawiki/skins/CologneBlue/+/857766
• Example – No changes needed!
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/MinervaNeue/+/857767
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/Modern/+/857768
• MonoBook – No changes needed!
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/Nostalgia/+/857769
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/Timeless/+/857770
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/Vector/+/842860

Extension and skin patches that depend on new HTML: [Should be merged after core]

• https://gerrit.wikimedia.org/r/c/mediawiki/extensions/DiscussionTools/+/842937
• https://gerrit.wikimedia.org/r/c/mediawiki/extensions/VisualEditor/+/859139
• https://gerrit.wikimedia.org/r/c/mediawiki/extensions/MobileFrontend/+/857772
• https://gerrit.wikimedia.org/r/c/mediawiki/extensions/PageImages/+/860553
• https://gerrit.wikimedia.org/r/c/mediawiki/extensions/Scribunto/+/860555
• https://gerrit.wikimedia.org/r/c/mediawiki/extensions/LabeledSectionTransclusion/+/860577
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/MinervaNeue/+/860582
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/Vector/+/860583

Utilities for testing: [Do not merge]

• https://gerrit.wikimedia.org/r/c/mediawiki/core/+/860125
• https://gerrit.wikimedia.org/r/c/mediawiki/skins/MinervaNeue/+/860099

(All patches: https://gerrit.wikimedia.org/r/q/topic:heading-markup-T13555)

Might be a good time Soon to User-notice this so gadget authors can get started on a migration.

Let's add the tag as a reminder, but I think we should wait with sending the announcement until I have the code running on the beta cluster, or at least on PatchDemo (I couldn't create a demo wiki because it didn't like something about so many dependencies, I hope it'll work after we merge some of the preparatory patches so that I don't need to debug why). Note that the markup changes in core are behind a configuration flag, which I'll turn off on Wikimedia wikis at first, so this won't take effect immediately after the patches are merged.

There may be Parsoid/VisualEditor changes needed as well. We'll need to decide whether to change the heading structure in "edit mode" HTML, or whether this is a transformation of the "editable" HTML which only applies to read views.

I have a patch up for VisualEditor that adjusts it for these changes: https://gerrit.wikimedia.org/r/c/mediawiki/extensions/VisualEditor/+/859139. Parsoid does not currently have section edit links, or any other "embellishments" on the headings, so I did not propose any changes for it.

When we will be adding them, I would prefer to make it a transformation that only applies to read views. I could work on that, but I thought that the necessary "framework" for doing that doesn't exist yet, although I know it's planned – if (or when) it exists, please point it out and I'll write some patches.