Heading HTML changes

The HTML markup of headings on wikitext pages will change in 2024 as part of MediaWiki 1.42. 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
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. The change does not apply to most special pages, nor to Parsoid edit-mode content, which will continue to use simple  markup.

Why this is changing
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
If you haven't had a chance to update your skin to style the new markup, a skin option is temporarily available to restore the old markup: TODO. This option will be removed in the future.

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

Skins and sitewide styles
Skins that use  configured with   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 it may be cached in parser cache), and the simple markup with no wrappers (used by most special pages and Parsoid edit-mode content).

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


 * 1) Wherever you used a selector like , add.
 * 2) Wherever you used a selector like , add.
 * 3) Wherever you used the selector , add.
 * 4) For any styles applied to both   and , unset them when the heading is nested in the wrapper, using a selector like.

Once you drop compatibility with MediaWiki 1.41, you can remove selectors that were only needed to support the old markup (such as  or  ).

Example changes:

Extensions and gadgets
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
After the changes are deployed, 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  markup, not only when using the wikitext   markup), and because editing the template style page will purge the parser cache of pages using it.