Parsoid/Parser Unification/Media structure/FAQ

Overview

What do you mean by media structure?

When files are included in a page (example: [[File:Foobar.jpg|thumb|caption|alt=alt]]), MediaWiki's parser outputs some HTML that represents that media for your browser to render – the instructions for the browser so that it is correctly shown on your screen. The choice of HTML tags and attributes, and how they are arranged to form a DOM tree, are the structure we're considering.

What can be improved about the current structure?

The current structure is composed of nested div tags and class attributes, which don't convey much meaning. The markup is irregular, making it harder to query and style. And the current output differs from that of other products, like the VisualEditor / Parsoid combo. See the RFC for the finer details. The output for the example above looks like this currently:

<div class="thumb tright">
    <div class="thumbinner" style="width:242px;">
        <a href="/wiki/File:Foobar.jpg" class="image"><img alt="alt" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" class="thumbimage" /></a>
        <div class="thumbcaption"><div class="magnify"><a href="/wiki/File:Foobar.jpg" class="internal" title="Enlarge"></a></div>caption</div>
    </div>
</div>

What are you replacing it with?

The structure we're replacing it with is composed of semantic markup, which will provide accessibility benefits, such as giving those who read the wikis using screenreaders more information about how images, videos and other media are used within the content. The markup will be more regular and specified, making it easier and more efficient to query and style, meaning that the new structure will make it easier for anyone writing CSS related to media on the Wikimedia wikis. Moreover, using the same structure that has been piloted in Parsoid will provide consistency between products and reduce some CSS redundancy. The output for the example above will look like this:

<figure class="mw-default-size" typeof="mw:File/Thumb">
    <a href="/wiki/File:Foobar.jpg" class="mw-file-description">
        <img alt="alt" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" class="mw-file-element" />
    </a>
    <figcaption>caption</figcaption>
</figure>

Why are you doing this now?

A medium term goal of the Content Transform Team at the WMF is to replace MediaWiki's legacy parser with Parsoid, a bidirectional wikitext to HTML5 parser. In order to get there, the legacy parser and Parsoid need to produce compatible HTML. Parsoid has been generating this new media structure for quite some time, to good effect. In order to lessen the disruption of changing parsers all at once, we're rolling out an isolated piece in preparation for further changes to come.

How has this been tested?

The new structure has been piloted in Parsoid which is used in several active products like Visual Editor and the mobile apps. As editors and readers used these products, they flagged rendering differences with the old structure and problems with the new structure, which we've fixed over the years.
In addition, we've done several rounds of visual difference testing where thousands of pages are rendered with the old and new structure and the rendering compared at a pixel level.
We've also already deployed this change to several wikis, including mediawiki.org, wikitech, it.wikipedia.org, cs.wikipedia.org, vi.wikipedia.org, en.wikivoyage.org, and all the group 0 wikis.

What's left to do?

Code that interacts with the page, like JavaScript for extensions, user scripts and gadgets will need to be adjusted to the new structure, hopefully in a forwards and backwards compatible way.
Skins will need to ask for the "content-media" feature or provide their own styling, since classes targeting the old structure won't apply.
Some wikis have CSS in MediaWiki:Commons.css that will need to be ported to the new structure.

When will you be rolling this out?

As above, it's already live on several wikis. However, we won't continue to push forward until the known issues are addressed and we've done some level of auditing of user scripts and gadgets to ensure we're causing as little disruption to readers and editors as possible.

What about imagemaps and galleries?

The output for these extension tags builds on the media structure outlined above. They are specified at, respectively, ImageMap and Gallery. Note that further refining of the gallery output may happen in T268250.

What about templates that mimic the parser output?

For now, the stylesheets shipped by MediaWiki will continue to contain the rules that target the old parser output. Therefore templates that mimic it should continue to work unchanged. As mentioned above, we've done extensive visual difference testing to ensure that pages continue to render the same before and after these changes. In the longer term, we are discussing introducing new classes for these templates to migrate towards. See T318433 for details.

What about site owners operating their own instances of MediaWiki?

A MediaWiki config exists, $wgParserEnableLegacyMediaDOM , which currently defaults to true. Site operators are encouraged to disable it and test for possible breakage. Skins that use ResourceLoaderSkinModule configured with "features": { "content-media": true } will receive styles targeting the new structure. In future versions of MediaWiki, $wgParserEnableLegacyMediaDOM will default to false and, eventually, be removed entirely.

How can I help?

Test your code on the wikis we've deployed to. If you find any problems that are not covered below, please file tasks with the tag Parsoid-Read-Views (Phase 0 - Parsoid-Media-Structure), or see the list of open tasks.

Copy known fixes to gadgets enabled on your wikis

A number of gadgets were identified as needing to be updated to support the new media structure. Fixes were applied to the source of the gadgets but the changes still need to propagate out to all the wikis that have duplicated the gadgets locally. See the task description of T297447 for the list of gadgets and wikis where the gadgets are enabled. If yours haven't been updated, please do so.

Copy known fixes to MediaWiki:Common.(css|js) to your wikis

A number of issues with site specific css and js were identified as needing to be updated to support the new media structure. See the task description of T271114 for the list of known issues common to multiple wikis and the wikis that may need to be updated. If yours haven't been updated, please do so.

What should editors look out for?

The "image" class is no longer present on file description links

By default, a file (e.g. [[File:Foobar.jpg]]) will link to its description page and would previously be given a class named image.

<a href="/wiki/File:Foobar.jpg" class="image"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" /></a>

In contrast, an explicit link (e.g. [[File:Foobar.jpg|link=Hello]]) would not result in that class being applied.

<a href="/wiki/Hello" title="Hello"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" /></a>

In the new structure, the class serving the same purpose has been renamed to mw-file-description.

<span class="mw-default-size" typeof="mw:File"><a href="/wiki/File:Foobar.jpg" class="mw-file-description"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" class="mw-file-element" /></a></span>

Selectors should target the new class, where appropriate. For example, see https://www.mediawiki.org/w/index.php?title=Snippets%2FDirect_imagelinks_to_Commons&type=revision&diff=5451422&oldid=3976429

The `|class=` media option is now applied to the wrapper

Previously, the class media option (e.g. [[File:Foobar.jpg|class=my_special_class]]) would be applied to the media element.

<a href="/wiki/File:Foobar.jpg" class="image"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" class="my_special_class" /></a>

The class has been moved to the outer wrapper, in order to allow the most flexibility when selecting within the structure.

<span class="mw-default-size my_special_class" typeof="mw:File"><a href="/wiki/File:Foobar.jpg" class="mw-file-description"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" class="mw-file-element" /></a></span>

The `|border` media option is now applied to the wrapper and the class emitted has been renamed

Previously, the border media option (e.g. [[File:Foobar.jpg|border]]) would result in the thumbborder class being applied to the media element.

<a href="/wiki/File:Foobar.jpg" class="image"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" class="thumbborder" /></a>

For consistency, the class has been moved to the outer wrapper and renamed to mw-image-border to prevent conflicts.

<span class="mw-default-size mw-image-border" typeof="mw:File"><a href="/wiki/File:Foobar.jpg" class="mw-file-description"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" class="mw-file-element" /></a></span>

Horizontal and vertical alignment options now place classes on the wrapper

The horizontal alignment options include left, right, center, and none. The vertical alignment options include baseline, sub, super, top, text-top, middle, bottom, and text-bottom.

For example, previously, the center media option (e.g. [[File:Foobar.jpg|center]]) would result in the center class being applied to a wrapping div.

<div class="center"><div class="floatnone"><a href="/wiki/File:Foobar.jpg" class="image"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" /></a></div></div>

This now results in a figure with the mw-halign-center class.

<figure class="mw-default-size mw-halign-center" typeof="mw:File"><a href="/wiki/File:Foobar.jpg" class="mw-file-description"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" class="mw-file-element" /></a><figcaption></figcaption></figure>

Similarly, the top media option (e.g. [[File:Foobar.jpg|top]]) would previously result a style attribute being applied to the media element.

<a href="/wiki/File:Foobar.jpg" class="image"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" style="vertical-align: top" /></a>

This now results in the mw-valign-top class being applied to the wrapper.

<span class="mw-default-size mw-valign-top" typeof="mw:File"><a href="/wiki/File:Foobar.jpg" class="mw-file-description"><img alt="Foobar.jpg" src="https://upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg" decoding="async" width="240" height="28" class="mw-file-element" /></a></span>