Specs/HTML

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

See Parsoid/HTML5 DOM with microdata for the general idea and background. This is work in progress, feel free to suggest improvements! See http://rdfa.info/ for RDFa documentation and a live parser.

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.

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.

Thumbnails
 

Strawman new version:  

 

 

See enwiki help for all options

Semantic info in HTML/RDFa

 * 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
 * figcaption sub-element: The caption
 * resource attribute on image: link to image resource page. TODO: what to use for images from commons?
 * width and height on image: thumb size spec
 * alt attribute on image: alt property or caption
 * 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.

Simple image
 

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

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  Foo  would need to return an href="/Foo" instead.

 alternate linked content 

 Main Page </tt>

Link with tail:  Potatoes </tt>

Category links
 </tt>

 </tt>

Language links
 Foo </tt>

Interwiki non-language links
Status: In development / not yet implemented! See bug 42160.

 en:Foo </tt>

Autolinked URLs
 http://example.com </tt>

Numbered external link
 </tt>

Named external link
 Link content </tt>

ISBN link
 ISBN 978-1413304541 </tt>

RFC link
 RFC 1945 </tt>

PMID link
 PMID 20610307 </tt>

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.

 foo  </tt>

HTML entities
 œ </tt>

Behavior switches
Help:Magic_words. Not yet implemented, tracked in 37909.

 </tt>

 </tt>

<tt> __NEWSECTIONLINK__ </tt>

<tt> __NONEWSECTIONLINK__ </tt>

<tt> __NOGALLERY__ </tt>

<tt> __HIDDENCAT__ </tt>

<tt> __NOCONTENTCONVERT__ </tt>

<tt> __NOCC__ </tt>

<tt> __NOTITLECONVERT__ </tt>

<tt> __NOTC__ </tt>

<tt> </tt>

<tt> __NOINDEX__ </tt>

<tt> __INDEX__ </tt>

<tt> __STATICREDIRECT__ </tt>

Template content
Implementation progress tracked in bug 37911.

<tt> </tt> <meta about="#mw-t1" property="mwns10:Foo#1" content="unused value"> <meta about="#mw-t1" property="mw:src" content="http://en.wikipedia.org/wiki/Template:Foo">


 * Define a global prefix for the template namespace (mwt0 in this case). Reasoning: Prefix definitions are scoped to a DOM subtree, so the prefix definition would need to be repeated for multi-rooted template output. This should also be easier to figure out, and makes semantic sense since we are talking about the same property even if it is transcluded repeatedly. The trailing colon in the namespace URL apparently needs to be urlencoded, at least to satisfy http://rdf.info/play.

Non-semantic parameter editing
This is ready for implementation, see bug 44555.

The semantic markup used for template parameters makes sense for parameters containing semantic information. Unfortunately many parameters contain arbitrary wikitext, styles, template names and other non-semantic strings. We still want to make these editable without polluting the RDFa namespace with non-semantic data. We also have very little information which attributes are semantic and which are presentational. For now, we will thus expose all attributes in a simpler JSON attribute:

<tt> </tt> <meta about="#mw-t1" property="mw:TemplateParams" content='[{ "target": "Template:Foo", "params": {"1":"unused value","key":"used value","id":"},             "id:": "t1234"           }]'>

The (optional) id property will let us associate inline parameters with the JSON data later. This lets us support inline editing of things like infobox parameters in the future without changes to the JSON data structure.

Editing compound content blocks that include output from several templates like this football table would benefit from access to interspersed content from the surrounding page. We will implement this by interspersing wikitext strings with template information in the mw:TemplateParams array:

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.

Templates in attributes
<tt> Some text content </tt>

<tt> <div style="">... </tt>

The exact content of the attribute content for editing purposes could be serialized HTML DOM. Alternatively we could include that directly as a sub-dom in a div-wrapped section at the start or end of the document.

Extension content
<tt> </tt>

TODO: We use mw:Object/Extension/tagname for other extensions, which is easy for escaping etc. Switch Cite to the same scheme (mw:Object/Extension/ref and /references).

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

<tt> foo bar baz </tt>

<tt> foo bar baz </tt>

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.
 * Unexpanded and expanded templates
 * template parameter references
 * noinclude, onlyinclude, includeonly
 * behavior switches (only typeof="mw:Placeholder" currently, source-based round-tripping)
 * tag extensions including citations (partly done)
 * redirects
 * ISBN / RFC / PMED autolinks
 * galleries (handled just like other tag extensions)
 * Spec versioning: Add an attribute on the body element or in the head that spells out the DOM spec revision. This allows us to evolve the DOM spec while still correctly reading older HTML revisions. We can also convert them to the latest verision on the fly.