Heading HTML changes
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.
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]External media: Before-and-after comparison of the screen reader experience |
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 users testing the new Parsoid parser (T269630)
- May 21–23, 2024 – New markup enabled for users of the MonoBook, Timeless, Modern, CologneBlue, and Nostalgia skins (T365078)
- June 4–6, 2024 – New markup enabled for users of the Vector legacy skin (T365736)
- June 11–13, 2024 – New markup enabled for users of the MinervaNeue skin (T365736)
- July 16–18, 2024 – New markup enabled for users of the Vector 2022 skin. At this point all major skins have been changed. (T367601)
MediaWiki releases
[edit]- MediaWiki 1.43 –
- Config option $wgParserEnableLegacyHeadingDOM added, defaults to legacy markup (change 842859)
- Bundled skins MonoBook and Timeless support the new markup
- MediaWiki 1.44 (tentative) –
- Config option $wgParserEnableLegacyHeadingDOM changed, it now defaults to the new markup if the skin indicates support (change 1023980)
- Bundled skins MinervaNeue, Vector legacy and Vector 2022 also support the new markup
- Future release
- Config option $wgParserEnableLegacyHeadingDOM removed, new markup is always used regardless of the skin
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:
- Wherever you used a selector like
h1, h2, h3, h4, h5, h6
, add.mw-heading
. - Wherever you used a selector like
hN
, add.mw-headingN
. - Wherever you used the selector
.mw-headline
, addh1, h2, h3, h4, h5, h6
. - 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
).
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:
- https://gerrit.wikimedia.org/r/c/mediawiki/skins/Timeless/+/857770/10/resources/screen-common.less
- https://fr.wikipedia.org/w/index.php?title=MediaWiki:Common.css&diff=prev&oldid=212874402
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:
- https://gerrit.wikimedia.org/r/c/mediawiki/core/+/1009803/1/resources/src/mediawiki.misc-authed-pref/rightClickEdit.js
- https://gerrit.wikimedia.org/r/c/mediawiki/extensions/VisualEditor/+/859139/12/modules/ve-mw/init/targets/ve.init.mw.ArticleTarget.js
- https://gerrit.wikimedia.org/r/c/mediawiki/extensions/MobileFrontend/+/857772/12/src/mobile.init/editor.js
- https://gerrit.wikimedia.org/r/c/mediawiki/skins/Vector/+/860583/9/resources/skins.vector.js/setupIntersectionObservers.js
- https://ru.wikipedia.org/w/index.php?title=MediaWiki:Gadget-edittop.js&diff=prev&oldid=136450234
- https://en.wiktionary.org/w/index.php?title=MediaWiki:Gadget-TabbedLanguages.js&diff=prev&oldid=78700885
- https://en.wikivoyage.org/w/index.php?title=MediaWiki:Gadget-ListingEditor2023.js&diff=prev&oldid=4832346
- https://fr.wikipedia.org/w/index.php?title=MediaWiki:Gadget-AncreTitres.js&diff=215319381&oldid=213586059
- https://commons.wikimedia.org/w/index.php?title=MediaWiki:Gadget-DelReqHandler.js&diff=prev&oldid=879159945
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: