As part of a long-term project to emit more semantic HTML (T12467) we would like to use `<figure>` tags around media (T51097). Specifically we would like to make the output of the PHP parser match the [Parsoid DOM specification for images](https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec#Images). A patch already exists in gerrit: [196532](https://gerrit.wikimedia.org/r/196532).
The benefits are:
1. Smaller, more semantic markup, replacing the current nested `<div>`s and class attributes.
* Even if the differences are minimized by gzip transfer encoding, smaller markup still results in less client-side memory in the browser DOM.
2. More regular markup which can be more efficiently queried in user gadgets.
* An example from a [wikimania 2015 talk](https://commons.wikimedia.org/w/index.php?title=File:Doing_Cool_Things_with_Wiki_Content_%28Parsoid_Power!%29.pdf&page=6): `document.querySelectorAll('figure, [typeof~="mw:Image"]');` will pull out all media from an article.
* Efficient matching also allows for easier re-styling / re-arranging of media.
3. Consistency between PHP and Visual Editor/Parsoid reduces CSS redundancy, visual differences during editing, and on-going maintenance costs.
4. Accessibility benefits for non-inline media.
* Captions are properly marked with semantic element, etc.
However, any change to our emitted HTML has some costs:
1. User gadgets and other downstream tools may need to be updated to handle the new media output.
2. IE6 through 8 will require a single line of JavaScript emitted in a `<script>` tag to ensure that the `<figure>` element is parsed correctly. (Modern HTML5 browsers have no issues, since `<figure>` is a valid HTML5 tag.)
* `document.createElement('figure')`, according to http://knockoutjs.com/documentation/component-custom-elements.html#note-custom-elements-and-internet-explorer-6-to-8
3. Stylesheets or skins may need to be updated (although WMF styles have support for the new markup already to support Visual Editor).
This RFC is a means to publicize the proposed change and give downstream users an opportunity to update their tools before it is deployed. Further, we'd like to collect blocking bugs here to ensure that any critical user gadgets are updated *before* the change goes live.
**SUMMARY OF CHANGES**
This section will give you a basic idea of what the mediawiki HTML would look like before and after the change; see the [Parsoid DOM specification](https://www.mediawiki.org/wiki/Parsoid/MediaWiki_DOM_spec#Images) for full details on the new markup.
**Example 1**
```
[[Image:Foo.jpg|left|<p>caption</p>]]
```
Current output of PHP parser (linebreaks added for readability):
```
<div class="floatleft">
<a href="/wiki/File:Foo.jpg" class="image" title="caption">
<img alt="caption" src="http://upload.wikimedia.org/wikipedia/commons/3/3a/Foo.jpg" width="1941" height="220" />
</a>
</div>
```
Proposed new output:
```
<figure typeof="mw:Image" class="mw-default-size">
<a href="./File:Foo.jpg">
<img resource="./File:Foo.jpg" src="http://upload.wikimedia.org/wikipedia/commons/3/3a/Foo.jpg" width="1941" height="220">
</a>
<figcaption><p>caption</p></figcaption>
</figure>
```
**Example 2**
```
[[Image:Foobar.jpg|thumb|left|baseline|caption content]]
```
Current output of PHP parser (linebreaks added for readability):
```
<div class="thumb tleft">
<div class="thumbinner" style="width:222px;">
<a href="/wiki/File:Foobar.jpg" class="image">
<img alt="" src="//upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Foobar.jpg/220px-Foobar.jpg"
width="220" height="26" class="thumbimage"
srcset="//upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg 1.5x, //upload.wikimedia.org/wikipedia/commons/3/3a/Foobar.jpg 2x"
data-file-width="240" data-file-height="28">
</a>
<div class="thumbcaption">
<div class="magnify">
<a href="/wiki/File:Foobar.jpg" class="internal" title="Enlarge"></a>
</div>
caption content
</div>
</div>
</div>
```
Proposed new output:
```
<figure typeof="mw:Image/Thumb" class="mw-halign-left mw-valign-baseline mw-default-size">
<a href="./File:Foobar.jpg">
<img src="//upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Foobar.jpg/220px-Foobar.jpg"
data-file-width="240" data-file-height="28" data-file-type="bitmap"
height="26" width="220"
resource="./Image:Foobar.jpg" />
</a>
<figcaption>caption content</figcaption>
</figure>
```