Specs/HTML/1.8.0/Extensions/Cite

This documentation is for an old version. The latest version is available at Specs/HTML/Extensions/Cite.

Changes since Specs/HTML/1.6.0/Extensions/Cite

T198221: Support directionality for reference

Preliminaries

An example with transcluded reference content,

<ref group='x' name='y'>{{Cite|foo|bar=baz}}</ref>

renders as follows. (Note the references section was autogenerated)

<p>
    <sup about="#mwt3" class="mw-ref" id="cite_ref-y_1-0" rel="dc:references" typeof="mw:Extension/ref" data-mw='{"name":"ref","body":{"id":"mw-reference-text-cite_note-y-1"},"attrs":{"group":"x","name":"y"}}'>
        <a href="./Main_Page#cite_note-y-1" style="counter-reset: mw-Ref 1;" data-mw-group="x"><span class="mw-reflink-text">[x 1]</span></a>
    </sup>
</p>


<div class="mw-references-wrap" typeof="mw:Extension/references" about="#mwt4" data-parsoid='{"group":"x","dsr":[52,52,0,0]}' data-mw='{"name":"references","attrs":{"group":"x"},"autoGenerated":true}'>
    <ol class="mw-references references" data-mw-group="x">
        <li about="#cite_note-y-1" id="cite_note-y-1">
            <a href="./Main_Page#cite_ref-y_1-0" data-mw-group="x" rel="mw:referencedBy"><span class="mw-linkback-text">↑ </span></a>
            <span id="mw-reference-text-cite_note-y-1" class="mw-reference-text"><cite class="citation" about="#mwt2" typeof="mw:Transclusion" data-mw='{"parts":[{"template":{"target":{"wt":"Cite","href":"./Template:Cite"},"params":{"1":{"wt":"foo"},"bar":{"wt":"baz"}},"i":0}}]}'>...</cite></span>
        <li>
    </ol>
</div>

Ref and References

First one <ref>One</ref>
Second one <ref>Two <p>p1</p> <p>p2</p> </ref>
Named one <ref name='three'>Three</ref>
Reused <ref name='three' />
Reused again <ref name='three' />

<references />

The HTML output for this wikitext is shown below. Parsoid provides the element id of the HTML via the data-mw.body.id property rather than copying the HTML dom in the data-mw.body.html property. But, both formats are considered valid and Parsoid accepts both formats when serializing HTML to wikitext.

If data-mw.body.id is specified, it is the client's responsibility to make sure that the element id is present in the DOM. If both data-mw.body.html and data-mw.body.id are specified, Parsoid uses the html property and ignores the id property.

<p>
    First one
    <sup about="#mwt2" class="mw-ref" id="cite_ref-1" rel="dc:references" typeof="mw:Extension/ref"
            data-mw='{"name":"ref","body":{"id":"mw-reference-text-cite_note-1"},"attrs":{}}'>
        <a href="./Main_Page#cite_note-1" style="counter-reset: mw-Ref 1;"><span class="mw-reflink-text">[1]</span></a>
    </sup>
    Second one
    <sup about="#mwt4" class="mw-ref" id="cite_ref-2" rel="dc:references" typeof="mw:Extension/ref"
            data-mw='{"name":"ref","body":{"id":"mw-reference-text-cite_note-2"},"attrs":{}}'>
        <a href="./Main_Page#cite_note-2" style="counter-reset: mw-Ref 2;"><span class="mw-reflink-text">[2]</span></a>
    </sup>
    Named one
    <sup about="#mwt6" class="mw-ref" id="cite_ref-three_3-0" rel="dc:references" typeof="mw:Extension/ref"
            data-mw='{"name":"ref","body":{"id":"mw-reference-text-cite_note-three-3"},"attrs":{"name":"three"}}'>
        <a href="./Main_Page#cite_note-three-3" style="counter-reset: mw-Ref 3;"><span class="mw-reflink-text">[3]</span></a>
    </sup>
    Reused
    <sup about="#mwt8" class="mw-ref" id="cite_ref-three_3-1" rel="dc:references" typeof="mw:Extension/ref"
            data-mw='{"name":"ref","attrs":{"name":"three"}}'>
        <a href="./Main_Page#cite_note-three-3" style="counter-reset: mw-Ref 3;"><span class="mw-reflink-text">[3]</span></a>
    </sup>
    Reused again
    <sup about="#mwt10" class="mw-ref" id="cite_ref-three_3-2" rel="dc:references" typeof="mw:Extension/ref"
            data-mw='{"name":"ref","attrs":{"name":"three"}}'>
        <a href="./Main_Page#cite_note-three-3" style="counter-reset: mw-Ref 3;"><span class="mw-reflink-text">[3]</span></a>
    </sup>
</p>

<div class="mw-references-wrap" typeof="mw:Extension/references" about="#mwt12" data-mw='{"name":"references","attrs":{}}'>
    <ol class="mw-references references">
        <li about="#cite_note-1" id="cite_note-1">
            <a href="./Main_Page#cite_ref-1" rel="mw:referencedBy"><span class="mw-linkback-text">↑ </span></a>
            <span id="mw-reference-text-cite_note-1" class="mw-reference-text">One</span>
        </li>
        <li about="#cite_note-2" id="cite_note-2">
            <a href="./Main_Page#cite_ref-2" rel="mw:referencedBy"><span class="mw-linkback-text">↑ </span></a>
            <span id="mw-reference-text-cite_note-2" class="mw-reference-text">Two <p data-parsoid='{"stx":"html"}'>p1</p> <p data-parsoid='{"stx":"html"}'>p2</p> </span>
        </li>
        <li about="#cite_note-three-3" id="cite_note-three-3">
            <span rel="mw:referencedBy">
                <a href="./Main_Page#cite_ref-three_3-0"><span class="mw-linkback-text">1 </span></a>
                <a href="./Main_Page#cite_ref-three_3-1"><span class="mw-linkback-text">2 </span></a>
                <a href="./Main_Page#cite_ref-three_3-2"><span class="mw-linkback-text">3 </span></a>
            </span>
            <span id="mw-reference-text-cite_note-three-3" class="mw-reference-text">Three</span>
        </li>
    </ol>
</div>

Auto-generated references blocks

If the source wikitext had <ref> tags but no corresponding <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, for all such auto-generated reference block, the data-mw will have the autoGenerated property set to true.

Responsive wrappers

In T159894, support was added for the cite extension's responsive parameter, which presents the references section as multiple columns based on the browser window size. This is achieved by wrapping the ordered list with a div. Of note, since this is part of the extension content, the transclusion annotations are placed on the wrapper.

Directionality

A mw-cite-dir-XXX class is added to the reference list item based on the dir attribute specified on the reference definition. For example,

First one <ref dir="ltr">One</ref>

<references />

renders as,

<p>
    First one
    <sup about="#mwt2" class="mw-ref" id="cite_ref-1" rel="dc:references" typeof="mw:Extension/ref"
            data-mw='{"name":"ref","body":{"id":"mw-reference-text-cite_note-1"},"attrs":{"dir":"ltr"}}'>
        <a href="./Main_Page#cite_note-1" style="counter-reset: mw-Ref 1;"><span class="mw-reflink-text">[1]</span></a>
    </sup>
</p>

<div class="mw-references-wrap" typeof="mw:Extension/references" about="#mwt12" data-mw='{"name":"references","attrs":{}}'>
    <ol class="mw-references references">
        <li about="#cite_note-1" id="cite_note-1" class="mw-cite-dir-ltr">
            <a href="./Main_Page#cite_ref-1" rel="mw:referencedBy"><span class="mw-linkback-text">↑ </span></a>
            <span id="mw-reference-text-cite_note-1" class="mw-reference-text">One</span>
        </li>
    </ol>
</div>