Heading HTML changes

From mediawiki.org


The HTML markup of headings on wikitext pages will change in 2023 as part of MediaWiki 1.40. A wrapper is added around each heading, and elements other than text (such as section edit links) are 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 that 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.

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 until MediaWiki 1.41 there will be a config option to disable this, and because old markup may be cached in parser cache), and the simple markup with no wrappers (used by most special pages).

As a general guideline, for every selector applying to page content (e.g. .mw-body or #mw-content-text) – but not for selectors applying to skin interface (e.g. #mw-navigation) – apply the following changes:

  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 you drop compatibility with MediaWiki 1.40, you can remove selectors that were only needed to support the old markup (such as .mw-headline or hN .mw-editsection).

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:

Template styles[edit]

After your site's configuration is changed, you only need to worry about the new markup, because simple markup with no wrappers can't appear on content pages (the wrappers are added even to wikitext using HTML-style <h2> markup, not only when using the wikitext == markup), and because editing the template style page will purge the parser cache of pages using it.

Instructions for site owners[edit]

Until MediaWiki 1.41 there will be a config option to disable this…