Libx CommonMark Basics and Leaf Blocks

    On this page

    2.5Entity and numeric character references

    Valid HTML entity references and numeric character references can be used in place of the corresponding Unicode character, with the following exceptions:

    • Entity and character references are not recognized in code blocks and code spans.

    • Entity and character references cannot stand in place of special characters that define structural elements in CommonMark. For example, although * can be used in place of a literal * character, * cannot replace * in emphasis delimiters, bullet list markers, or thematic breaks.

    Conforming CommonMark parsers need not store information about whether a particular character was represented in the source using a Unicode character or an entity reference.

    Entity references consist of & + any of the valid HTML5 entity names + ;. The document https://html.spec.whatwg.org/entities.json is used as an authoritative source for the valid entity references and their corresponding code points.

    Example 25 
      & © Æ Ď
¾ ℋ ⅆ
∲ ≧̸

    <p>  &amp; © Æ Ď
¾ ℋ ⅆ
∲ ≧̸</p>

    Decimal numeric character references consist of &# + a string of 1–7 arabic digits + ;. A numeric character reference is parsed as the corresponding Unicode character. Invalid Unicode code points will be replaced by the REPLACEMENT CHARACTER (U+FFFD). For security reasons, the code point U+0000 will also be replaced by U+FFFD.

    Example 26 
    &#35; &#1234; &#992; &#0;

    <p># Ӓ Ϡ �</p>

    Hexadecimal numeric character references consist of &# + either X or x + a string of 1-6 hexadecimal digits + ;. They too are parsed as the corresponding Unicode character (this time specified with a hexadecimal numeral instead of decimal).

    Example 27 
    &#X22; &#XD06; &#xcab;

    <p>&quot; ആ ಫ</p>

    Here are some nonentities:

    Example 28 
    &nbsp &x; &#; &#x;
&#87654321;
&#abcdef0;
&ThisIsNotDefined; &hi?;

    <p>&amp;nbsp &amp;x; &amp;#; &amp;#x;
&amp;#87654321;
&amp;#abcdef0;
&amp;ThisIsNotDefined; &amp;hi?;</p>

    Although HTML5 does accept some entity references without a trailing semicolon (such as &copy), these are not recognized here, because it makes the grammar too ambiguous:

    Example 29 
    &copy

    <p>&amp;copy</p>

    Strings that are not on the list of HTML5 named entities are not recognized as entity references either:

    Example 30 
    &MadeUpEntity;

    <p>&amp;MadeUpEntity;</p>

    Entity and numeric character references are recognized in any context besides code spans or code blocks, including URLs, link titles, and fenced code block info strings:

    Example 31 
    <a href="&ouml;&ouml;.html">

    <a href="&ouml;&ouml;.html">
    Example 32 
    [foo](/f&ouml;&ouml; "f&ouml;&ouml;")

    <p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
    Example 33 
    [foo]

[foo]: /f&ouml;&ouml; "f&ouml;&ouml;"

    <p><a href="/f%C3%B6%C3%B6" title="föö">foo</a></p>
    Example 34 
    ``` f&ouml;&ouml;
foo
```

    <pre><code class="language-föö">foo
</code></pre>

    Entity and numeric character references are treated as literal text in code spans and code blocks:

    Example 35 
    `f&ouml;&ouml;`

    <p><code>f&amp;ouml;&amp;ouml;</code></p>
    Example 36 
        f&ouml;f&ouml;

    <pre><code>f&amp;ouml;f&amp;ouml;
</code></pre>

    Entity and numeric character references cannot be used in place of symbols indicating structure in CommonMark documents.

    Example 37 
    &#42;foo&#42;
*foo*

    <p>*foo*
<em>foo</em></p>
    Example 38 
    &#42; foo

* foo

    <p>* foo</p>
<ul>
<li>foo</li>
</ul>
    Example 39 
    foo&#10;&#10;bar

    <p>foo

bar</p>
    Example 40 
    &#9;foo

    <p>	foo</p>
    Example 41 
    [a](url &quot;tit&quot;)

    <p>[a](url &quot;tit&quot;)</p>