Specs/HTML/1.2.1

This page defines a MediaWiki-specific DOM based on HTML5 and RDFa. The semantics of MediaWiki-specific functionality are encoded using RDFa.

Changes since Specs/HTML/1.2.0

 * section specifies charset encoding via
 * section now provides HTML version number via
 * When a references block is auto-generated, the  tag now records this information by adding "autoGenerated": true to the   attribute

RDFa structures
Global prefix mappings:
 * Convention: Capital for types, lowercase for attributes.
 * Generally use the prefix instead of vocab definitions to avoid clashes (and allow mixing) with user-supplied RDFa. User-supplied RDFa with the mw prefix is moved to a non-clashing prefix in Parsoid.
 * Generally use the prefix instead of vocab definitions to avoid clashes (and allow mixing) with user-supplied RDFa. User-supplied RDFa with the mw prefix is moved to a non-clashing prefix in Parsoid.

Versioning
An integer version number is set in the head section of the returned HTML document. This version is incremented whenever this DOM spec or any other important aspect of the Parsoid HTML output changes. See bug 52937 for details.

mw:Placeholder and general client behavior
A  protects DOM structures from any editing. Clients are expected to preserve / protect subtrees marked as such. Clients are also expected to preserve any DOM subtrees marked up with,  ,   in the http://mediawiki.org/rdf/ namespace they don't understand. This decouples clients from Parsoid development, and lets them concentrate on editing constructs whose special semantics they understand without having to implement all possible content elements.

Images
Status: Implemented. Followup work to be done, Tracking bug.

In the examples below, the original size of the example image is 1941 × 220 pixels (these are the dimensions of the Foobar.jpg used in parserTests). The width and height in the DOM represent the actual scaled image height (not the bounding box dimensions specified in the wikitext). When image dimensions are modified or images with a non-default size are created, we will serialize to a square bounding box around the given width and/or height attributes. In the future: When using a (possibly scaled) version of the default thumbnail size, we will serialize using the  or   option to enforce a square thumbnail bounding box (see ).

The basic tree structure of all images, regardless of formatting options, alignment, or thumbnails, is: The outer &lt;figure&gt; element needs to become a &lt;span&gt; element when the figure is rendered inline, since otherwise the HTML5 parser will interrupt a surrounding block context. The inner &lt;figcaption&gt; element is rendered as a  attribute in this case (since block content in an invisible caption would otherwise break parsing). The inner &lt;a&gt; element needs to become a span if there is no link; see. An "alt" attribute on the &lt;img&gt; is present if (and only if) the "alt=" options are present in the wikitext markup. If the "lang=" option is present, the &lt;img&gt; tag will have a "lang" attribute. The "resource" attribute on the &lt;img&gt; tag specifies the wiki title and namespace for the image (so it doesn't have to be reverse-engineered from the "src" attribute); it should point to a relative URL based on the image title. The "link=" option will be present in generated wikitext if and only if the "resource" attribute of &lt;img&gt; differs from the "href" attribute of the &lt;a&gt; tag.

The &lt;img&gt; tag will have,  , and   attributes indicating the original (unscaled) size and type of the image. See.

See 118520 for a proposal to replace the &lt;span> with &lt;figure-inline> when the figure in rendered inline.

Summary of semantic info for images
Summary of semantic info that is present in the HTML generated for images:
 * wrapper node: for block images and  for inline images
 * typeof attribute on the wrapper: mw:Image, mw:Image/Thumb, mw:Image/Frame, mw:Image/Frameless for different image uses
 * figure classes: mw-valign-{baseline,middle,sub,super,text-top,text-bottom,top,bottom}, mw-halign-{left,right,center,none} and optionally mw-image-border and mw-default-size for full-size images and thumbs scaled to the wiki's and user's default thumb size
 * figcaption sub-element: The caption
 * resource attribute on image: link to image resource page. TODO: what to use for images from commons?
 * width and / or height on image: scaled image size. Only one of width or height is fine for easier client-side scaling without aspect ratio issues.
 * alt attribute on image: alt property
 * src attribute on image: thumb governed by explicit thumb option or implicit from image
 * href attribute on a around image: link target, normally just the image page- BUT a element can be absent if link is explicitly empty.

Specific image examples:
(Note 1)

Without a link, we use the same basic DOM structure, but use a span instead of an a wrapper (see bug 44627): (Note 1)

Adding 'left' causes the image to be rendered in block context, so the outer &lt;span&gt; becomes a &lt;figure&gt;: (Note 2, Note 5)

Scaling, vertical alignment of an inline image: (Note 1)

Caption (containing disallowed markup) on an inline image: (Note 2, Note 5)

(Note 2)

(Note 3, Note 4)

(Note 3)

(Note 5)

Note that "border" can be combined with "frameless". (Note 5)

Manual thumbnails; note that the  attribute points at the original image, the   attribute points to the manually-specific thumbnail image, and the   attribute indicates the resource name of the thumbnail (so it doesn't have to be inferred from the  ):

Resizing images with the "scale" option:

Resizing thumbs with the "scale" option (this is a square 220x220px bounding box, see 62671):

Resizing with the "upright" option (note that this is converted to an appropriate "scale" option, see above):

See enwiki help for all options, see mw for inline/float details

Note 1: The PHP parser adds a default alt attribute to the &lt;img&gt; tag, with content "Foobar.jpg". Client-side post-processing will need to add this for compatibility. (Parsoid does not add this attribute because it does not correspond to anything in the wikitext.)

Note 2: In this case the PHP parser adds a title attribute to the &lt;a&gt; and an alt attribute to the &lt;img&gt;, both with the value "caption". Note that this is a markup-stripped version of the supplied caption in some cases. Client-side post-processing will need to add these.

Note 3: The PHP parser adds a  element inside the &lt;figure&gt;. Post-processing can add this if needed by a client.

Note 4: The default thumbnail width is a user-specified preference for the PHP parser. Parsoid uses a fixed 220px thumbnail width. The "mw-default-size" class indicates "no size given" and can be used to resize thumbs according to user preferences.

Note 5: In this example, the caption is not visible in PHP output, so the there should be a rule in the default stylesheet like (IE7+ and other modern browsers): In the PHP parser output, the caption does appear as a title attribute on the &lt;a&gt; and an alt attribute on the &lt;img&gt;; client side post-processing should add these (unless there are existing title and alt attributes, resulting from "title=" and "alt=" properties in the wikitext).

Audio/Video (Proposal)
Status: To be finalized and implemented (See Tracking bug for details and progress.)

The basic  wrapper for audio and video media is identical to that for images, described in the section above, including provisions for inline players and captions. (Note that the PHP implementation does not properly render manual thumbnails or inline.)

The inner  element tracks the elements emitted by the video.js implementation in T100106.

Notes:
 * "thumbtime needs to be matched" (CSA: I forget exactly what this means; presumably we need to represent this parameter in the HTML.)
 * Some of the  attributes should probably be   attributes for consistency.  As a general rule, attributes derived from inspection of the original media file (original size, bandwidth, framerate, etc) should get   prefixes.  Attributes of derived/transcoded media can be plain   attributes. T133670
 * The wikitext  options does not exist for video (it can be specified but not added to output, spec defines it should not be present since accessibility for video is via captions specified by the   element).  We probably need to represent this hidden attribute in.
 * The wikitext  option does not exist for video (it can be specified but is not added to output) -- videos always produce , never  .  We probably need to represent this hidden attribute in.
 * The  text can/should be radically minimized; perhaps eliminated.  In particular, HTML5 video support means that "JavaScript disabled" shouldn't prevent the video from being viewed. T133671
 * The  and   tags are ignored during HTML-to-wikitext serialization; all information encoded in wikitext is represented on the ,  ,  , and   elements.
 * An audio element has no dimensions, as it has no 'visible area'. Any space you give it is basically styling information on the UI of the player that you overlay on your element. What to do with the dimensions for audio elements ? T133673
 * There is an existing noicon parameter that no longer does anything (but is still present in a lot of wikitext, and excepted as a valid option by the TMH extension) T134880
 * There is a disablecontrols option (and accompanying --data-disablecontrols). This option allows wikitext users to hide individual controls from the toolbar. This seems hardly used, other than by the Score extension. We will need an approach for this...
 * will only be present on transcoded sources, not on original files.
 * It is not guaranteed that the original file is one of the sources listed.....

Wiki links

 * The href attribute is UTF8 (as everything else), with a relative link prefix that always navigates up to the top of the wiki namespace, especially in subpages / pages containing slashes in the title. Example: './Foo', or (in a subpage) './../Foo'. We percent-encode percents and question marks in hrefs to support following links to wiki pages with question marks in their name. On the way in (when posting HTML to Parsoid) we assume href values to be urlencoded and decode them during serialization. Modified link hrefs without ./ or ../ prefix are temporarily assumed to be absolute to the wiki namespace for now, but will also be interpreted as relative to the page soon to support relative links in other HTML content. After that change, the equivalent of an absolute wikilink  would need to return an href="/Foo" instead.

Link with tail:

Nowiki blocks
There are two options to handle nowiki editing:
 * 1) Strip the tags from the DOM and let the serializer add those that are needed after each edit
 * 2) Keep them in the DOM for more accurate round-tripping of manually created nowiki blocks, and prevent non-text content from being entered into these blocks in the editor (TODO)

We picked option 2 for now. The nowiki content remains editable. If the content is modified in a way that makes nowiki unnecessary Parsoid can remove the wrapper in the serializer.

Category default sort key

 * See bug 46470. Status: ready for implementation.

Redirects
(T104502: This no longer creates a category.)

Note that interwiki links generate redirect tags; the client is responsible for not doing an HTTP 301 or 302 redirect to an external site.

Note that, unlike the PHP parser, using language links still generates correct redirect tags in Parsoid. The client is again responsible for not doing an HTTP redirect to an external wiki.

Transclusion content
Many transclusion parameters contain arbitrary wikitext, styles, template names and other non-semantic / DOM strings. We also have very little information which attributes are semantic and which are presentational. So for now, we will thus expose all attributes in the "wt" (wikitext) format:

The  property is used to associate additional information with each transclusion or extension fragment. This lets us support inline editing of things like infobox parameters in the future without changes to the JSON data structure.

Parameter names are represented by their index, if not explicitly named, or by the name that will be used when replacing them. In the case that the normalized parameter named is different from the actual parameter name in the text, a key.wt attribute is used to keep the name as it appears in the text. For example:

Compound content blocks that include output from several transclusions like this football table is represented by interspersing wikitext strings with transclusion information in the data-mw.parts array:




 * $$1+1$$
 * }
 * }

Editing support for the interspersed wikitext is difficult to implement on the server side, as those wikitext edits need to be restricted in their effect to the original DOM range. A potential solution to this could be to wrap the multi-template compound block into a template hook that expands its content to a well-balanced DOM structure. Arbitrary wikitext edits within this tag would still only affect the original DOM range, both in Parsoid and the PHP parser. This is lower priority though, so for now the interspersed wikitext will be read-only.

Parameter Substitution at the top-level
This section specifies wrapping for parameter uses in the top-level namespace where all parameter substitutions evaluate to a null value.

Transclusion-affected attributes
'''Status: Implemented. See bug 52913.'''

This is the representation of attributes in links, tables, and html tags whose keys and/or values are fully or partially generated by transclusions. When only attributes are affected, the element is be assigned an "mw:ExpandedAttrs" typeof attribute and the data-wm JSON object will provide additional specific information about the keys or values that are fully or partially generated by templates. If other parts of the content are also transclusion-affected, the element will be marked up according as a general transclusion instead.

It is conceivable to think up use-cases where part of an attribute value is generated by a template (ex: color of a background-color of a style attribute), but not as much for attribute-keys. This spec also assumes that a template can only generate one attribute rather than multiple attributes.

A few examples are worked out below.

Example 1:

Example 2: ...

Example 3:

Extension content
The data-mw attribute is a JSON object. It is meant as an extensible public interface, so more top-level members can be added. The top-level structure depends on the content type, with the main types being transclusions and extensions. See also the transclusion content section.

At present, Parsoid has few native extension handlers. As a fallback, it places the raw extension body text in  for clients to edit in a raw-text editor. See the implemented extensions below for details on editing their content.

Ref and References
First one Second one Named one Reused Reused again

Auto-generated references blocks
If the source wikitext had &lt;ref> tags but no corresponding &lt;references> tag to generate references, Parsoid auto-generates references blocks for every set of refs that need it. As of HTML version 1.2.1 (as of Friday, March 25, 2016, the production version of Parsoid on the WMF cluster is still at version 1.2.0), for all such auto-generated reference block, the data-mw will have the autoGenerated property set to true.

noinclude / includeonly / onlyinclude
Not yet implemented, tracked in 40305. We only care about these in the actual page context, not in transcluded pages / templates.

Language conversion blocks
Status: provisional / strawman. See bug 41716 and /Language conversion blocks.

Error handling
See bug 48900.
 * For API errors because of a non-existing image, data-mw.errors.key is set to "missing-image".
 * For API errors getting image info, data-mw.errors.key is set to "api-error" and data-mw.errors.message has more information about the specific error.
 * For image wikitext where a manual thumbnail is specified and it is not present, the data-mw.errors.key is set to "missing-thumbnail" and data-mw.errors.message is set to "This thumbnail does not exist.".

Ex:

Ex:

Recent changes
Some cleanup is needed (from bug 53432): In https://gerrit.wikimedia.org/r/232284 the following was changed:
 * mw:WikiLink/Interwiki became mw:ExtLink, and we automatically detect interwiki prefixes in new/modified mw:ExtLink content.
 * mw:ExtLink/* became just mw:ExtLink. The information can mostly be extracted by matching a href prefix. Client-side rendering of numbered external links can be handled with CSS as discussed in bug 53505.
 * mw:WikiLink/Category became mw:PageProp/Category as these are not really links. They don't render at all in the page, don't accept a caption etc.
 * mw:WikiLink/Language became mw:PageProp/Language - same as with categories.
 * 1) template-affected attributes were moved to data-mw (see #Transclusion-affected attributes)
 * 1) ISBNs became mw:WikiLink instead of mw:ExtLink.  More discussion at https://phabricator.wikimedia.org/T63558#1217861

ID attributes on all elements
We will also assign ID attributes to all elements, and use this to associate external metadata with those elements: /Element_IDs. We will eventually move data-parsoid (private, so should not matter to users) and likely also data-mw (public) from the DOM into JSON objects keyed on the ID.

TODO
The following constructs still need a RDFa markup definition. They will initially only be marked with typeof="mw:Placeholder" for simple read-only round-tripping.
 * template parameter references (implemented, but not tested much)
 * extension as HTML5 sections (see bug 47936).
 * extension as HTML5 sections (see bug 47936).