Heading HTML changes

From mediawiki.org

The HTML markup of headings on wikitext pages will change in 2024 as part of MediaWiki 1.43. A wrapper will be added around each heading, and elements other than text (such as section edit links) will be moved from the heading itself to the wrapper. (T13555)

What's changing[edit]

There should be no visual changes for editors and readers. However, maintainers of skins, extensions and gadgets that affect headings will need to update them to avoid issues for their users.

Example old and new HTML source for heading tags
Old HTML New HTML 
<h2>
    <span class="mw-headline" id="...">Heading</span>
    <span class="mw-editsection">...</span>
</h2>

<div class="mw-heading mw-heading2">
    <h2 id="...">Heading</h2>
    <span class="mw-editsection">...</span>
</div>

The change does not apply to most special pages, nor to Parsoid edit-mode content, which will continue to use simple <h2>...</h2> markup.

Why this is changing[edit]

This change will improve accessibility for people using screen readers. It's a common workflow to navigate around a page by the headings present on it, like an automatically generated table of contents. With the old markup, interface elements like section edit links were a part of each heading, causing them to be read out along with every heading's text. The problem was exacerbated by extensions that added further interface elements to headings, such as VisualEditor's "edit source" links and DiscussionTools's "subscribe" buttons.

Opting out[edit]

There is no user preference available to control this behavior.

Site owners may use the config option $wgParserEnableLegacyHeadingDOM to control which markup is used. This option will be removed in a future release of MediaWiki.

Skin developers may use the supportsMwHeading skin option to control which markup is used. This option will be removed in a future release of MediaWiki.

When using Parsoid for page views, the new markup is used unconditionally.

Timeline[edit]

Wikimedia wikis[edit]

  • January 2023 – As a trial for this change, “hybrid” markup with wrappers is introduced for level-2 headings on discussion pages using DiscussionTools (T314714)
  • December 2023 – Implementation of wrappers is corrected (T353489)
  • February 2024 – New markup enabled for all users testing the new Parsoid parser (T269630)
  • May 2024 – New markup enabled for all users of the MonoBook, Timeless, Modern and CologneBlue skins (T365078)
  • Future – New markup enabled for everyone (users of the MinervaNeue, Vector legacy and Vector 2022 skins)

MediaWiki releases[edit]

Instructions for updating code[edit]

Skins and sitewide styles[edit]

Skins that use ResourceLoaderSkinModule configured with "features": { "elements": true } may not need any changes at all, since the built-in heading styles were updated.

Your styles should be compatible with three kinds of markup at the same time: the new markup, the old markup (because site owners may choose to use it), and the simple markup with no wrappers (used by most special pages and Parsoid edit-mode content).

As a general guideline, styles for the heading blocks (e.g. background or borders) need to apply to both .mw-heading and h1-h6 (except when nested in .mw-heading), while styles for heading text (e.g. fonts and text colors) need to apply to h1-h6 and .mw-headline.

You can follow these rules of thumb to update your code:

  1. Wherever you used a selector like h1, h2, h3, h4, h5, h6, add .mw-heading.
  2. Wherever you used a selector like hN, add .mw-headingN.
  3. Wherever you used the selector .mw-headline, add h1, h2, h3, h4, h5, h6.
  4. For any styles applied to both hN and .mw-headingN, unset them when the heading is nested in the wrapper, using a selector like .mw-heading hN.

Once the config option for site owners is removed in a future release of MediaWiki, you will be able to remove selectors that were only needed to support the old markup (such as .mw-headline or hN .mw-editsection).

Example changes
Old CSS Upgraded CSS 
h2 {
    border: 1px solid black;
    background-color: red;
    color: white;
    font-size: 2em;
}

.mw-heading2, h2 {
    border: 1px solid black;
    background-color: red;
    color: white;
    font-size: 2em;
}
.mw-heading2 h2 {
    border: none;
    font-size: inherit;
}

Example changes:

Extensions and gadgets[edit]

There isn't a simple pattern like for styles, but in general you'll need to update your code to work with either of the HTML structures. Sometimes it can be as easy as changing the selectors, similar to the section above.

Example changes:

Wiki content[edit]

TemplateStyles targeting plain h2 etc. selectors need to be updated similarly to skins, see above. Once all skins in your wiki use the new markup, you will be able to remove selectors that were only needed to support the old markup (such as .mw-headline or hN .mw-editsection).

Inline styles, and TemplateStyles targeting custom CSS classes, do not require any changes, because the wrappers are not added on headings written using HTML-style <h2> markup if there are attributes. Doing so caused too many issues with existing markup, and the motivation for the change does not apply, because these headings do not have interface elements like section edit links (T353489#9416500).

Example changes:

Retrieved from "https://www.mediawiki.org/w/index.php?title=Heading_HTML_changes&oldid=6538029"