HTML 5.3

Flow content.

Palpable content.

Where flow content is expected.

Phrasing content.

A p element’s end tag may be omitted if the p element is immediately followed by an address, article, aside, blockquote, details, div, dl, fieldset, figcaption, figure, footer, form, h1, h2, h3, h4, h5, h6, header, hr, main, nav, ol, p, pre, section, table, or ul, element, or if there is no more content in the parent element and the parent element is an HTML element that is not an a, audio, del, ins, map, noscript, or video element.

Any role value.

Any aria-* attributes applicable to the default or allowed roles.

interface HTMLParagraphElement : HTMLElement {};

The p element represents a block of content, a paragraph as defined in this specification. The p element should not be used when a more specific element, such as a list, is more appropriate.

Some block elements cannot be children of p elements. When the parser finds them, it automatically closes the p element - effectively inserting a </p> tag. These elements are: heading content, most sectioning roots and sectioning content, form, fieldset, table, ol, ul, and legend.

Paragraphs are usually represented visually as blocks of text, separated from adjacent blocks by blank lines. However a style sheet or user agent may present paragraph breaks in a different manner, for instance using inline pilcrows (¶).

The following examples are conforming HTML fragments:

<p>The little kitten gently seated itself on a piece of carpet. Later in his life, this would be referred to as the time the cat sat on the mat.</p>

<p>There was once an example from Femley,<br>
Whose markup was of dubious quality.<br>
The validator complained,<br>
So the author was pained,<br>
To move the error from the markup to the rhyming.</p>;

The following example is technically conforming HTML:

<section>
  <!-- ... -->
  <p>Last modified: 2001-04-23</p>
  <p>Author: fred@example.com</p>
</section>

However, it would be better marked-up as:

<section>
  <!-- ... -->
  <footer>Last modified: 2001-04-23</footer>
  <address>Author: fred@example.com</address>
</section>

Or:

<section>
  <!-- ... -->
  <footer>
    <p>Last modified: 2001-04-23</p>
    <address>Author: fred@example.com</address>
  </footer>
</section>

Among others, list elements (e.g. li, ol, and ul) cannot be children of p elements. So to mark up a sentence that contains a list, like the following:

For instance, this fantastic sentence has bullets relating to

wizards,
faster-than-light travel, and
telepathy,

and is further discussed below.

it is important to remember that a paragraph in HTML does not have the semantic meaning of "a single idea" that is a usual part of how English grammar describes "paragraphs". Instead it is merely a default type of block-level structure for content. In the example above, there are five block-level structures: one before the list, one for each bullet, and one after the list.

The markup for the above example could therefore be:

<p>For instance, this fantastic sentence has bullets relating to</p>
<ul>
  <li>wizards,</li>
  <li>faster-than-light travel, and</li>
  <li>telepathy,</li>
</ul>
<p>and is further discussed below.</p>

Authors wishing to conveniently style such "logical" paragraphs consisting of multiple "structural" paragraphs can use the div element instead of, or as well as the p element.

Thus for instance the above example could become the following:

<div>For instance, this fantastic sentence has bullets relating to
  <ul>
    <li>wizards,</li>
    <li>faster-than-light travel, and</li>
    <li>telepathy,</li>
  </ul>
and is further discussed below.</div>

<div>
  <p>For instance, this fantastic sentence has bullets relating to</p>
  <ul>
    <li>wizards,</li>
    <li>faster-than-light travel, and</li>
    <li>telepathy,</li>
  </ul>
  <p>and is further discussed below.</p>
</div>

These examples still have five structural blocks, but now the author can style just the div instead of having to consider each part of the example separately.

4.4.2. The `address` element

Categories:: Flow content.; Palpable content.
Contexts in which this element can be used:: Where flow content is expected.
Content model:: Flow content, but with no heading content descendants, no sectioning content descendants, and no main, header, footer, or address element descendants.
Tag omission in text/html:: Neither tag is omissible
Content attributes:: Global attributes
Allowed ARIA role attribute values:: Any role value.
Allowed ARIA state and property attributes:: Global aria-* attributes; Any aria-* attributes applicable to the allowed roles.
DOM interface:: Uses HTMLElement.

The address element represents contact information for a person, people or organization. It should include physical and/or digital location/contact information, and a means of identifying a person(s) or organization the information pertains to.

For example, the W3C twitter account:

<address>
  <p>W3C on Twitter:</p>
  <p><a href="https://twitter.com/w3c">@w3c</a></p>
</address>

Address, telephone and fax numbers for an organization:

<address>
  UNIVERSITY INTERSCHOLASTIC LEAGUE<br>
  1701 Manor Road, Austin, TX 78722<br>
  Tel: (512) 471-5883 | Fax: (512) 471-5908
</address>

The address part of a form output:

...
<label for="name">Name:</label> <input type="text" id="name">
<label for="hn">House number:</label> <input type="text" id="hn">
<label for="street">Street:</label> <input type="text" id="street">
...
<address>
  <p>Name: Hament Dhanji</p>
  <p>House number: 123</p>
  <p>Street: Example Road</p>
  ...
</address>

Location of a cat:

<address>
  Lola the cat is at
  Latitude: 51.47852
  Longitude: -0.1449519
</address>

The meaning and usage contexts of the address element is broad. If developers wish to provide more granular and specific semantics for the address element, it is suggested to use of any of the various semantic web metadata schemas.

For example, the postal address of a local business annotated using RDFa:

<div vocab="http://schema.org/" typeof="LocalBusiness">
  <h1><span property="name">Beachwear & Giftware</span></h1>
  <p property="description">
    A superb collection of fine gifts and clothing to accent your stay in Mexico Beach.
  </p>
 <address property="address" typeof="PostalAddress"> 
  <span property="streetAddress">123 Example Street</span>
  <span property="addressLocality">Mexico Beach</span>,
  <span property="addressRegion">FL</span>
 </address> 
  Phone: <span property="telephone">(212) 664-7665</span>
</div>

4.4.3. The `hr` element

Flow content.

Where flow content is expected.

Nothing.

No end tag.

separator (default - do not set), none or presentation.

Any aria-* attributes applicable to the default or allowed roles.

interface HTMLHRElement : HTMLElement {};

DPub Roles:

doc-pagebreak

The hr element represents a paragraph-level thematic break, such as a scene change in a story, or a transition to another topic within a section of a reference book.

The following fictional extract from a project manual shows two sections that use the hr element to separate topics within the section.

<section>
  <h1>Communication</h1>
  <p>There are various methods of communication. This section covers a few of the important ones used by the project.</p>
  <hr>
  <p>Communication stones seem to come in pairs and have mysterious properties:</p>
  <ul>
    <li>They can transfer thoughts in two directions once activated if used alone.</li>
    <li>If used with another device, they can transfer one’s consciousness to another body.</li>
    <li>If both stones are used with another device, the consciousnesses switch bodies.</li>
  </ul>
  <hr>
  <p>Radios use the electromagnetic spectrum in the meter range and longer.</p>
  <hr>
  <p>Signal flares use the electromagnetic spectrum in the nanometer range.</p>
</section>
<section>
  <h1>Food</h1>
  <p>All food at the project is rationed:</p>
  <dl>
    <dt>Potatoes</dt>
    <dd>Two per day</dd>
    <dt>Soup</dt>
    <dd>One bowl per day</dd>
  </dl>
  <hr>
  <p>Cooking is done by the chefs on a set rotation.</p>
</section>

There is no need for an hr element between the sections themselves, since the section elements and the h1 elements imply thematic changes themselves.

The following extract from Pride and Prejedice by Jane Austen shows a paragraph that precedes a scene change and the paragraph that follows it. The scene change, represented in the printed book by a gap containing a solitary centered star between the second and third paragraphs, is here represented using the hr element.

<p>
  Elizabeth told her the motives of her secrecy. She had been unwilling to mention Bingley; and the unsettled state of her own feelings had made her equally avoid the name of his friend. But now she would no longer conceal from her his share in Lydia’s marriage. All was acknowledged, and half the night spent in conversation.
</p>
<hr>
<p>
  “Good gracious!” cried Mrs. Bennet, as she stood at a window the next morning, “if that disagreeable Mr. Darcy is not coming here again with our dear Bingley! What can he mean by being so tiresome as to be always coming here? I had no notion but he would go a-shooting, or something or other, and not disturb us with his company. What shall we do with him? Lizzy, you must walk out with him again, that he may not be in Bingley’s way.”
</p>

The hr element does not affect the document’s outline.

4.4.4. The `pre` element

Flow content.

Palpable content.

Where flow content is expected.

Phrasing content.

Neither tag is omissible

Any role value.

Any aria-* attributes applicable to the default or allowed roles.

interface HTMLPreElement : HTMLElement {};

The pre element represents a block of preformatted text, in which structure is represented by typographic conventions rather than by elements.

In the HTML syntax, a leading newline character immediately following the pre element start tag is stripped.

Some examples of cases where the pre element could be used:

Including an e-mail, with paragraphs indicated by blank lines, lists indicated by lines prefixed with a bullet, and so on.
Including fragments of computer code, with structure indicated according to the conventions of that language.
Displaying ASCII art.

Authors are encouraged to consider how preformatted text will be experienced when the formatting is lost, as will be the case for users of speech synthesizers, braille displays, and the like. For cases like ASCII art, it is likely that an alternative presentation, such as a textual description, would be more universally accessible to the readers of the document.

To represent a block of computer code, the pre element can be used with a code element; to represent a block of computer output the pre element can be used with a samp element. Similarly, the kbd element can be used within a pre element to indicate text that the user is to enter.

This element has rendering requirements involving the bidirectional algorithm.

In the following snippet, a sample of computer code is presented.

<p>This is the <code>Panel</code> constructor:</p>
<pre><code>function Panel(element, canClose, closeHandler) {
  this.element = element;
  this.canClose = canClose;
  this.closeHandler = function () { if (closeHandler) closeHandler() };
}</code></pre>

In the following snippet, samp and kbd elements are mixed in the contents of a pre element to show a session of Zork I.

<pre><samp>You are in an open field west of a big white house with a boarded
front door.
There is a small mailbox here.

></samp> <kbd>open mailbox</kbd>

<samp>Opening the mailbox reveals:
A leaflet.

></samp></pre>

The following shows a contemporary poem that uses the pre element to preserve its unusual formatting, which forms an intrinsic part of the poem itself.

<pre>                maxling

it is with a          heart
                heavy

that i admit loss of a feline
        so           loved

a friend lost to the
        unknown
                                (night)

~cdr 11dec07</pre>

4.4.5. The `blockquote` element

Flow content.

Sectioning root.

Palpable content.

Where flow content is expected.

Flow content.

Neither tag is omissible

cite - Link to the source of the quotation.

Any role value.

Any aria-* attributes applicable to the default or allowed roles.

interface HTMLQuoteElement : HTMLElement {
  attribute DOMString cite;
};

The HTMLQuoteElement interface is also used by the q element.

The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a footer or cite element, and optionally with in-line changes such as annotations and abbreviations.

Content inside a blockquote other than citations and in-line changes must be quoted from another source, whose address, if it has one, may be cited in the cite attribute.

In cases where a page contains contributions from multiple people, such as comments on a blog post, 'another source' can include text from the same page, written by another person.

If the cite attribute is present, it must be a valid URL potentially surrounded by spaces. To obtain the corresponding citation link, the value of the attribute must be parsed relative to the element’s node document. User agents may allow users to follow such citation links, but they are primarily intended for private use (e.g., by server-side scripts collecting statistics about a site’s use of quotations), not for readers.

The cite IDL attribute must reflect the element’s cite content attribute.

The content of a blockquote may be abbreviated, may have context added or may have annotations. Any such additions or changes to quoted text must be indicated in the text (at the text level). This may mean the use of notational conventions or explicit remarks, such as "emphasis mine".

For example, in English, abbreviations are traditionally identified using square brackets. Consider a page with the sentence "Fred ate the cracker. He then said he liked apples and fish."; it could be quoted as follows:

<blockquote>
  <p>[Fred] then said he liked [...] fish.</p>
</blockquote>

Quotation marks may be used to delineate between quoted text and annotations within a blockquote.

For example, an in-line note provided by the author:

<figure>
  <blockquote>
    "That monster custom, who all sense doth eat Of habit’s devil," <abbr title="et cetera">&c.</abbr> not in Folio

    "What a falling off was there! From me, whose love was of that dignity That it went hand in hand even with the vow I made to her in marriage, and to decline Upon a wretch."
  </blockquote>
  <footer>
    — <cite class="title">Shakespeare manual</cite> by <cite class="author">Frederick Gard Fleay</cite>, p19 (in Google Books)
  </footer>
</figure>

In the example above, the citation is contained within the footer of a figure element, this groups and associates the information, about the quote, with the quote. The figcaption element was not used, in this case, as a container for the citation as it is not a caption.

Attribution for the quotation, may be be placed inside the blockquote element, but must be within a cite element for in-text attributions or within a footer element.

For example, here the attribution is given in a footer after the quoted text, to clearly relate the quote to its attribution:

<blockquote>
  <p>I contend that we are both atheists. I just believe in one fewer god than you do. When you understand why you dismiss all the other possible gods, you will understand why I dismiss yours.</p>
  <footer>— <cite>Stephen Roberts</cite></footer>
</blockquote>

Here the attribution is given in a cite element on the last line of the quoted text. Note that a link to the author is also included.

<blockquote>
  The people recognize themselves in their commodities; they find their soul in their automobile, hi-fi set, split-level home, kitchen equipment. — <cite><a href="https://en.wikipedia.org/wiki/Herbert_Marcuse">Herbert Marcuse</a></cite>
</blockquote>

Here the attribution is given in a footer after the quoted text, and metadata about the reference has been added using the RDFA Lite syntax. [rdfa-lite]

<blockquote>
  <p>... she said she would not sign any deposition containing the word "amorous" instead of "advances". For her the difference was of crucial significance, and one of the reasons she had separated from her husband was that he had never been amorous but had consistently made advances.</p>

  <footer typeof="schema:Book">
    <span property="schema:author">Heinrich Böll</span>,
    <span property="schema:name">The Lost Honor of Katharina Blum</span>,
    <span property="schema:datePublished">January 1, 1974</span>
  </footer>
</blockquote>

There is no formal method for indicating the markup in a blockquote is from a quoted source. It is suggested that if the footer or cite elements are included and these elements are also being used within a blockquote to identify citations, the elements from the quoted source could be annotated with metadata to identify their origin, for example by using the class attribute (a defined extensibility mechanism).

In this example the source of a quote includes a cite element, which is annotated using the class attribute:

<blockquote>
  <p>My favorite book is <cite class="from-source">At Swim-Two-Birds</cite></p>
  <footer>- <cite>Mike[tm]Smith</cite></footer>
</blockquote>

The other examples below show other ways of showing attribution.

Here a blockquote element is used in conjunction with a figure element and its figcaption:

<figure>
  <blockquote>
    <p>The truth may be puzzling. It may take some work to grapple with. It may be counterintuitive. It may contradict deeply held prejudices. It may not be consonant with what we desperately want to be true. But our preferences do not determine what’s true.</p>
    <p>We have a method, and that method helps us to reach not absolute truth, only asymptotic approaches to the truth — never there, just closer and closer, always finding vast new oceans of undiscovered possibilities. Cleverly designed experiments are the key.</p>
  </blockquote>
  <figcaption>
    <cite>Carl Sagan</cite>, in "<cite>Wonder and Skepticism</cite>", from the <cite>Skeptical Inquirer</cite> Volume 19, Issue 1 (January-February 1995)
  </figcaption>
</figure>

This next example shows the use of cite alongside blockquote:

<p>His next piece was the aptly named <cite>Sonnet 130</cite>:</p>
<blockquote cite="https://quotes.example.org/s/sonnet130.html">
  <p>My mistress' eyes are nothing like the sun,<br>
  Coral is far more red, than her lips red,<br>
  ...

This example shows how a forum post could use blockquote to show what post a user is replying to. The article element is used for each post, to mark up the threading.

<article>
  <h1><a href="https://bacon.example.com/?blog=109431">Bacon on a crowbar</a></h1>
  <article>
    <header><strong>t3yw</strong> 12 points 1 hour ago</header>
    <p>I bet a narwhal would love that.</p>
    <footer><a href="?pid=29578">permalink</a></footer>
    <article>
      <header><strong>greg</strong> 8 points 1 hour ago</header>
      <blockquote>
        <p>I bet a narwhal would love that.</p>
      </blockquote>
      <p>Dude narwhals don’t eat bacon.</p>
      <footer><a href="?pid=29579">permalink</a></footer>
      <article>
        <header><strong>t3yw</strong> 15 points 1 hour ago</header>
        <blockquote>
          <blockquote>
            <p>I bet a narwhal would love that.</p>
          </blockquote>
          <p>Dude narwhals don’t eat bacon.</p>
        </blockquote>
        <p>Next thing you’ll be saying they don’t get capes and wizard hats either!</p>
        <footer><a href="?pid=29580">permalink</a></footer>
        <article>
          <header><strong>boing</strong> -5 points 1 hour ago</header>
          <p>narwhals are worse than ceiling cat</p>
          <footer><a href="?pid=29581">permalink</a></footer>
        </article>
      </article>
    </article>
    <article>
      <header><strong>fred</strong> 1 points 23 minutes ago</header>
      <blockquote>
        <p>I bet a narwhal would love that.</p>
      </blockquote>
      <p>I bet they’d love to peel a banana too.</p>
      <footer><a href="?pid=29582">permalink</a></footer>
    </article>
  </article>
</article>

This example shows the use of a blockquote for short snippets, demonstrating that one does not have to use p elements inside blockquote elements:

<p>She began a list of quotations with the following:</p>
<blockquote>It is a truth universally acknowledged, that a single man in possession of a good fortune, must be in want of a wife.</blockquote>
<p>She continued with a number of similar quotes, ending with:</p>
<blockquote>The person, be it gentleman or lady, who has not pleasure in a good novel, must be intolerably stupid.</blockquote>
<p>We shall now discuss these points...

Examples of how to represent a conversation are shown in a later section; it is not appropriate to use the cite and blockquote elements for this purpose.

4.4.6. The `ol` element

Flow content.

If the element’s children include at least one li element: Palpable content.

Where flow content is expected.

Zero or more li and script-supporting elements.

Neither tag is omissible

reversed - Number the list backwards.

start - Ordinal value of the first item

type - Kind of list marker.

list role (default - do not set), directory, group, listbox, menu, menubar, none, presentation, radiogroup, tablist, toolbar or tree.

Any aria-* attributes applicable to the default or allowed roles.

interface HTMLOListElement : HTMLElement {
  attribute boolean reversed;
  attribute long start;
  attribute DOMString type;
};

The ol element represents a list of items, where the items have been intentionally ordered, such that changing the order would change the meaning of the document.

The items of the list are the li element child nodes of the ol element, in tree order.

The reversed attribute is a boolean attribute. If present, it indicates that the list is a descending list (..., 3, 2, 1). If the attribute is omitted, the list is an ascending list (1, 2, 3, ...).

The start attribute, if present, must be a valid integer giving the ordinal value of the first list item.

If the start attribute is present, user agents must parse it as an integer, in order to determine the attribute’s value. The default value, used if the attribute is missing or if the value cannot be converted to a number according to the referenced algorithm, is 1 if the element has no reversed attribute, and is the number of child li elements otherwise.

The first item in the list has the ordinal value given by the ol element’s start attribute, unless that li element has a value attribute with a value that can be successfully parsed, in which case it has the ordinal value given by that value attribute.

Each subsequent item in the list has the ordinal value given by its value attribute, if it has one, or, if it doesn’t, the ordinal value of the previous item, plus one if the reversed is absent, or minus one if it is present.

The type attribute can be used to specify the kind of marker to use in the list, in the cases where that matters (e.g., because items are to be referenced by their number/letter). The attribute, if specified, must have a value that is a case-sensitive match for one of the characters given in the first cell of one of the rows of the following table. The type attribute represents the state given in the cell in the second column of the row whose first cell matches the attribute’s value; if none of the cells match, or if the attribute is omitted, then the attribute represents the decimal state.

Keyword	State	Description	Examples for values 1-3 and 3999-4001
`1` (U+0031)	decimal	Decimal numbers	`1.`	`2.`	`3.`	...	`3999.`	`4000.`	`4001.`	...
`a` (U+0061)	lower-alpha	Lowercase latin alphabet	`a.`	`b.`	`c.`	...	`ewu.`	`ewv.`	`eww.`	...
`A` (U+0041)	upper-alpha	Uppercase latin alphabet	`A.`	`B.`	`C.`	...	`EWU.`	`EWV.`	`EWW.`	...
`i` (U+0069)	lower-roman	Lowercase roman numerals	`i.`	`ii.`	`iii.`	...	`mmmcmxcix.`	`i̅v̅.`	`i̅v̅i.`	...
`I` (U+0049)	upper-roman	Uppercase roman numerals	`I.`	`II.`	`III.`	...	`MMMCMXCIX.`	`I̅V̅.`	`I̅V̅I.`	...

User agents should render the items of the list in a manner consistent with the state of the type attribute of the ol element. Numbers less than or equal to zero should always use the decimal system regardless of the type attribute.

For CSS user agents, a mapping for this attribute to the list-style-type CSS property is given in the §10 Rendering section (the mapping is straightforward: the states above have the same names as their corresponding CSS values).

It is possible to redefine the default CSS list styles used to implement this attribute in CSS user agents; doing so will affect how list items are rendered.

The reversed, start, and type IDL attributes must reflect the respective content attributes of the same name. The start IDL attribute has the same default as its content attribute.

The following markup shows a list where the order matters, and where the ol element is therefore appropriate. Compare this list to the equivalent list in the ul section to see an example of the same items using the ul element.

<p>I have lived in the following countries (given in the order of when I first lived there):</p>
<ol>
  <li>Switzerland</li>
  <li>United Kingdom</li>
  <li>United States</li>
  <li>Norway</li>
</ol>

Note how changing the order of the list changes the meaning of the document. In the following example, changing the relative order of the first two items has changed the birthplace of the author:

<p>I have lived in the following countries (given in the order of when I first lived there):</p>
<ol>
  <li>United Kingdom</li>
  <li>Switzerland</li>
  <li>United States</li>
  <li>Norway</li>
</ol>

4.4.7. The `ul` element

Flow content.

If the element’s children include at least one li element: Palpable content.

Where flow content is expected.

Zero or more li and script-supporting elements.

Neither tag is omissible

list role (default - do not set), directory, group, listbox, menu, menubar, presentation, radiogroup, tablist, toolbar or tree.

Any aria-* attributes applicable to the default or allowed roles.

interface HTMLUListElement : HTMLElement {};

The ul element represents a list of items, where the order of the items is not important — that is, where changing the order would not materially change the meaning of the document.

The items of the list are the li element child nodes of the ul element.

The following markup shows a list where the order does not matter, and where the ul element is therefore appropriate. Compare this list to the equivalent list in the ol section to see an example of the same items using the ol element.

<p>I have lived in the following countries:</p>
<ul>
  <li>Norway</li>
  <li>Switzerland</li>
  <li>United Kingdom</li>
  <li>United States</li>
</ul>

Note that changing the order of the list does not change the meaning of the document. The items in the snippet above are given in alphabetical order, but in the snippet below they are given in order of the size of their current account balance in 2007, without changing the meaning of the document whatsoever:

<p>I have lived in the following countries:</p>
<ul>
  <li>Switzerland</li>
  <li>Norway</li>
  <li>United Kingdom</li>
  <li>United States</li>
</ul>

4.4.8. The `li` element

None.

Inside ol elements.

Inside ul elements.

Flow content.

An li element’s end tag may be omitted if the li element is immediately followed by another li element or if there is no more content in the parent element.

If the element is not a child of an ul: value

listitem role (default - do not set), menuitem, menuitemcheckbox, menuitemradio, option, none, presentation, radio, separator, tab or treeitem.

Any aria-* attributes applicable to the default or allowed roles.

interface HTMLLIElement : HTMLElement {
  attribute long value;
};

DPub Roles:

doc-biblioentry or doc-endnote

The li element represents a list item. If its parent element is an ol, or ul, then the element is an item of the parent element’s list, as defined for those elements. Otherwise, the list item has no defined list-related relationship to any other li element.

If the parent element is an ol element, then the li element has an ordinal value.

The value attribute, if present, must be a valid integer giving the ordinal value of the list item.

If the value attribute is present, user agents must parse it as an integer, in order to determine the attribute’s value. If the attribute’s value cannot be converted to a number, the attribute must be treated as if it was absent. The attribute has no default value.

The value attribute is processed relative to the element’s parent ol element (q.v.), if there is one. If there is not, the attribute has no effect.

The value IDL attribute must reflect the value of the value content attribute.

The following example, the top ten movies are listed (in reverse order). Note the way the list is given a title by using a figure element and its figcaption element.

<figure>
  <figcaption>The top 10 movies of all time</figcaption>
  <ol>
    <li value="10"><cite>Josie and the Pussycats</cite>, 2001</li>
    <li value="9"><cite lang="sr">Црна мачка, бели мачор</cite>, 1998</li>
    <li value="8"><cite>A Bug’s Life</cite>, 1998</li>
    <li value="7"><cite>Toy Story</cite>, 1995</li>
    <li value="6"><cite>Monsters, Inc</cite>, 2001</li>
    <li value="5"><cite>Cars</cite>, 2006</li>
    <li value="4"><cite>Toy Story 2</cite>, 1999</li>
    <li value="3"><cite>Finding Nemo</cite>, 2003</li>
    <li value="2"><cite>The Incredibles</cite>, 2004</li>
    <li value="1"><cite>Ratatouille</cite>, 2007</li>
  </ol>
</figure>

The markup could also be written as follows, using the reversed attribute on the ol element:

<figure>
  <figcaption>The top 10 movies of all time</figcaption>
  <ol reversed>
    <li><cite>Josie and the Pussycats</cite>, 2001</li>
    <li><cite lang="sr">Црна мачка, бели мачор</cite>, 1998</li>
    <li><cite>A Bug’s Life</cite>, 1998</li>
    <li><cite>Toy Story</cite>, 1995</li>
    <li><cite>Monsters, Inc</cite>, 2001</li>
    <li><cite>Cars</cite>, 2006</li>
    <li><cite>Toy Story 2</cite>, 1999</li>
    <li><cite>Finding Nemo</cite>, 2003</li>
    <li><cite>The Incredibles</cite>, 2004</li>
    <li><cite>Ratatouille</cite>, 2007</li>
  </ol>
</figure>

While it is conforming to include heading elements (e.g., h2) and Sectioning content inside li elements, it likely does not convey the semantics that the author intended. A heading starts a new section, so a heading in a list implicitly splits the list into spanning multiple sections. Sectioning content explicitly creates a new section and so splits the list into spanning multiple sections.

4.4.9. The `dl` element

Flow content.

If the element’s children include at least one name-value group: Palpable content.

Where flow content is expected.

Either:Zero or more groups each consisting of one or more dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.

Or: One or more div elements, optionally intermixed with script-supporting elements.

Neither tag is omissible

list role (default - do not set), group, none or presentation.

Any aria-* attributes applicable to the default or allowed roles.

interface HTMLDListElement : HTMLElement {};

DPub Roles:

doc-glossary

The dl element represents a description list of zero or more term-description groups.

Each term-description group consists of one or more terms (represented by dt elements) and one or more descriptions (represented by dd elements.

The div element may be used as a child of the dl element (as a way to organize term-description groups consisting of one or more more dt elements, and one or more dd elements).

Term-description groups may be names and definitions, questions and answers, categories and topics, or any other groups of term-description pairs.

In this example a dl is used to represent a simple list of names and descriptions:

<dl>
  <dt>Blanco tequila</dt>
  <dd>The purest form of the blue agave spirit...</dd>
  <dt>Reposado tequila</dt>
  <dd>Typically aged in wooden barrels for between two and eleven months...</dd>
</dl>

Each term within a term-description group must be represented by a single dt element. The descriptions within a term-description group are alternatives. Each description must be represented by a single dd element.

In this example a dl element represents a set of terms, each of which has multiple descriptions:

<p>Information about the rock band Queen:</p>
<dl>
  <dt>Members</dt>
  <dd>Brian May</dd>
  <dd>Freddie Mercury</dd>
  <dd>John Deacon</dd>
  <dd>Roger Taylor</dd>
  <dt>Record labels</dt>
  <dd>EMI</dd>
  <dd>Parlophone</dd>
  <dd>Capitol</dd>
  <dd>Hollywood</dd>
  <dd>Island</dd>
</dl>

The div element may be used to contain a term-description group, consisting of at least one dt and at least one dd element.

In this example the div element is used as a styling container for a term-description group:

<dl>
  <div class="teas">
    <dt>Black teas</dt>
    <dd>Assam</dd>
    <dd>Darjeeling</dd>
  </div>
  <div>
    <dt>Green teas</dt>
    <dd>Gunpowder</dd>
  </div>
</dl>

A div element that is a child of a dl element, must contain at least one term-description group consisting of at least one dt element and at least one dd element.

In this example the div element is ignored because it does not contain a term-description group:

<dl>
  <div>
    <p>Important questions:</p>
  </div>
  <dt>What is the answer to life, the universe, and everything?</dt>
  <dd>42</dd>
</dl>

The order of term-description groups within a dl element, and the order of terms and descriptions within each group, may be significant.

In this example a dl is used to show a set of instructions, where the order of the instructions is important:

<p>Determine the victory points as follows (use the first matching case):</p>
<dl>
  <dt> If you have exactly five gold coins </dt>
  <dd> You get five victory points </dd>
  <dt> If you have one or more gold coins, and you have one or more silver coins </dt>
  <dd> You get two victory points </dd>
  <dt> If you have one or more silver coins </dt>
  <dd> You get one victory point </dd>
  <dt> Otherwise </dt>
  <dd> You get no victory points </dd>
</dl>

If a dl element contains no dt or dd child elements, it contains no term-description groups.

When a dl element does not match its content model, it is often because a dd element has been used instead of a dt element, or vice versa.

4.4.10. The `dt` element

Categories:: None.
Contexts in which this element can be used:: Before dd or dt elements inside dl elements.
Content model:: Flow content, but with no header, footer, sectioning content, or heading content descendants.
Tag omission in text/html:: A dt element’s end tag may be omitted if the dt element is immediately followed by another dt element or a dd element.
Content attributes:: Global attributes
Allowed ARIA role attribute values:: listitem role (default - do not set)
Allowed ARIA state and property attributes:: Global aria-* attributes; Any aria-* attributes applicable to the default role.
DOM interface:: Uses HTMLElement.

The dt element represents a term, part of a term-description group in a description list (dl element).

In this example the dt elements represent questions and the dd elements the answers:

<dl>
  <dt>What is my favorite drink?</dt>
  <dd>Tea</dd>
  <dt>What is my favorite food?</dt>
  <dd>Sushi</dd>
  <dt>What is my favourite film?</dt>
  <dd>What a Wonderful Life</dd>
</dl>

When used within a dl element, the dt element does not necessarily represent a term being defined. The dfn element should be used to represent a term being defined.

In this example the dfn element indicates that the dt element contains a defined term, the definition for which is represented by the dd element:

<dl>
  <dt lang="en-us"><dfn>Color</dfn></dt>
  <dt lang="en-gb"><dfn>Colour</dfn></dt>
  <dd>A sensation which (in humans) derives from the ability of the fine structure of the eye to distinguish three differently filtered analyses of a view.</dd>
</dl>

4.4.11. The `dd` element

Categories:: None.
Contexts in which this element can be used:: After dt or dd elements inside dl elements.
Content model:: Flow content.
Tag omission in text/html:: A dd element’s end tag may be omitted if the dd element is immediately followed by another dd element or a dt element, or if there is no more content in the parent element.
Content attributes:: Global attributes
Allowed ARIA role attribute values:: definition role (default - do not set)
Allowed ARIA state and property attributes:: Global aria-* attributes; Any aria-* attributes applicable to the default or allowed roles.
DOM interface:: Uses HTMLElement.

The dd element represents a description, part of a term-description group in a description list (dl element).

In this example the dd elements represent the keys that invoke the keycodes indicated in the dt elements:

<dl>
  <dt>37</dt>
  <dd>Left</dd>
  <dt>38</dt>
  <dd>Right</dd>
  <dt>39</dt>
  <dd>Up</dd>
  <dt>40</dt>
  <dd>Down</dd>
</dl>

4.4.12. The `figure` element

Categories:: Flow content.; Sectioning root.; Palpable content.
Contexts in which this element can be used:: Where flow content is expected.
Content model:: Flow content optionally including a figcaption child element.
Tag omission in text/html:: Neither tag is omissible
Content attributes:: Global attributes
Allowed ARIA role attribute values:: figure role (default - do not set), group, none or presentation.
Allowed ARIA state and property attributes:: Global aria-* attributes; Any aria-* attributes applicable to the default or allowed roles.
DOM interface:: Uses HTMLElement.

The figure element represents some flow content, optionally with a caption, that is self-contained (like a complete sentence) and is typically referenced as a single unit from the main flow of the document.

"Self-contained" in this context does not necessarily mean independent. For example, each sentence in a paragraph is self-contained; an image that is part of a sentence would be inappropriate for figure, but an entire sentence made of images would be fitting.

The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc.

When a figure is referred to from the main content of the document by identifying it by its caption (e.g., by figure number), it enables such content to be easily moved away from that primary content, e.g., to the side of the page, to dedicated pages, or to an appendix, without affecting the flow of the document.

If a figure element is referenced by its relative position, e.g., "in the photograph above" or "as the next figure shows", then moving the figure would disrupt the page’s meaning. Authors are encouraged to consider using labels to refer to figures, rather than using such relative references, so that the page can easily be restyled without affecting the page’s meaning.

The figcaption descendant of figure, if any, represents the caption of the figure element’s contents. If there is no child figcaption element, then there is no caption.

A figure element’s contents are part of the surrounding flow. If the purpose of the page is to display the figure, for example a photograph on an image sharing site, the figure and figcaption elements can be used to explicitly provide a caption for that figure. For content that is only tangentially related, or that serves a separate purpose than the surrounding flow, the aside element should be used (and can itself wrap a figure). For example, a pull quote that repeats content from an article would be more appropriate in an aside than in a figure, because it isn’t part of the content, it’s a repetition of the content for the purposes of enticing readers or highlighting key topics.

This example shows the figure element to mark up a code listing.

<p>In <a href="#l4">listing 4</a> we see the primary core interface API declaration.</p>
<figure id="l4">
  <figcaption>Listing 4. The primary core interface API declaration.</figcaption>
  <pre><code>interface PrimaryCore {
  boolean verifyDataLine();
  void sendData(in sequence&lt;byte> data);
  void initSelfDestruct();
}</code></pre>
</figure>
<p>The API is designed to use UTF-8.</p>

Here we see a figure element to mark up a photo that is the main content of the page (as in a gallery).

<!DOCTYPE html>
<title>Bubbles at work — My Gallery™</title>
<figure>
  <img src="bubbles-work.jpeg" alt="Bubbles, sitting in his office chair, works on his latest project intently.">
  <figcaption>Bubbles at work</figcaption>
</figure>
<nav><a href="19414.html">Prev</a> — <a href="19416.html">Next</a></nav>

In this example, we see an image that is not a figure, as well as an image and a video that are. The first image is literally part of the example’s second sentence, so it’s not a self-contained unit, and thus figure would be inappropriate.

<h2>Malinko’s comics</h2>

<p>This case centered on some sort of "intellectual property" infringement related to a comic (see Exhibit A). The suit started after a trailer ending with these words:</p>

<blockquote>
  <img src="promblem-packed-action.png" alt="ROUGH COPY! Promblem-Packed Action!">
</blockquote>

<p>...was aired. A lawyer, armed with a Bigger Notebook, launched a preemptive strike using snowballs. A complete copy of the trailer is included with Exhibit B.</p>

<figure>
  <img src="ex-a.png" alt="Two squiggles on a dirty piece of paper.">
  <figcaption>Exhibit A. The alleged <cite>rough copy</cite> comic.</figcaption>
</figure>

<figure>
  <video src="ex-b.mov"></video>
  <figcaption>Exhibit B. The <cite>Rough Copy</cite> trailer.</figcaption>
</figure>

<p>The case was resolved out of court.</p>

Here, a part of a poem is marked up using figure.

<figure>
  <p>'Twas brillig, and the slithy toves<br>
  Did gyre and gimble in the wabe;<br>
  All mimsy were the borogoves,<br>
  And the mome raths outgrabe.</p>
  <figcaption><cite>Jabberwocky</cite> (first verse). Lewis Carroll, 1832-98</figcaption>
</figure>

In this example, which could be part of a much larger work discussing a castle, nested figure elements are used to provide both a group caption and individual captions for each figure in the group:

<figure>
  <figcaption>The castle through the ages: 1423, 1858, and 1999 respectively.</figcaption>
  <figure>
    <figcaption>Etching. Anonymous, ca. 1423.</figcaption>
    <img src="castle1423.jpeg" alt="The castle has one tower, and a tall wall around it.">
  </figure>
  <figure>
    <figcaption>Oil-based paint on canvas. Maria Towle, 1858.</figcaption>
    <img src="castle1858.jpeg" alt="The castle now has two towers and two walls.">
  </figure>
  <figure>
    <figcaption>Film photograph. Peter Jankle, 1999.</figcaption>
    <img src="castle1999.jpeg" alt="The castle lies in ruins, the original tower all that remains in one piece.">
  </figure>
</figure>

The figure is sometimes referenced only implicitly from the content:

<article>
  <h1>Fiscal negotiations stumble in Congress as deadline nears</h1>
  <figure>
    <img src="obama-reid.jpeg" alt="Obama and Reid sit together smiling in the Oval Office.">
    <figcaption>Barack Obama and Harry Reid. White House press photograph.</figcaption>
  </figure>
  <p>Negotiations in Congress to end the fiscal impasse sputtered on Tuesday, leaving both chambers
  grasping for a way to reopen the government and raise the country’s borrowing authority with a
  Thursday deadline drawing near.</p>
  ...
</article>

4.4.13. The `figcaption` element

Categories:: None.
Contexts in which this element can be used:: As a descendant of a figure element.
Content model:: Flow content.
Tag omission in text/html:: Neither tag is omissible
Content attributes:: Global attributes
Allowed ARIA role attribute values:: group, none or presentation.
Allowed ARIA state and property attributes:: Global aria-* attributes; Any aria-* attributes applicable to the default or allowed roles.
DOM interface:: Uses HTMLElement.

The figcaption element represents a caption or legend for the rest of the contents of the figcaption element’s parent figure element, if any.

4.4.14. The `main` element

Categories:: Flow content.; Palpable content.
Contexts in which this element can be used:: Where flow content is expected, but only if it is a hierarchically correct main element.
Content model:: Flow content.
Tag omission in text/html:: Neither tag is omissible
Content attributes:: Global attributes
Allowed ARIA role attribute values:: main role (default - do not set).
Allowed ARIA state and property attributes:: Global aria-* attributes; Any aria-* attributes applicable to the default role.
DOM interface:: Uses HTMLElement

The main element represents the dominant contents of the document.

A document must not have more than one main element that does not have the §5.1 The hidden attribute attribute specified.

A hierarchically correct main element is one whose ancestor elements are limited to html, body, div, form without an accessible name, and autonomous custom elements. Each main element must be a hierarchically correct main element.

The main element is not sectioning content and has no effect on the document outline.

The main element is not suitable for identifying the main content areas of sub-sections of a document. The simplest solution is not to mark up the main content of a sub-section at all (leaving it as implicit), but an author could use §4.4 Grouping content or a sectioning content element as appropriate.

<!-- conforming example -->
<main>...</main>
<main hidden>...</main>
<main hidden>...</main>

<!-- non-conforming example -->
<main>...</main>
<main>...</main>
<main>...</main>

In the following example, we see 2 articles about skateboards (the main topic of a Web page) the main topic content is identified by the use of the main element.

<!-- other content -->

<main>

  <h1>Skateboards</h1>
  <p>The skateboard is the way cool kids get around</p>

  <article>
    <h2>Longboards</h2>
    <p>Longboards are a type of skateboard with a longer wheelbase and larger, softer wheels.</p>
    <p>... </p>
    <p>... </p>
  </article>

  <article>
    <h2>Electric Skateboards</h2>
    <p>These no longer require the propelling of the skateboard by means of the feet; rather an electric motor propels the board, fed by an electric battery.</p>
    <p>... </p>
    <p>... </p>
  </article>

</main>

<!-- other content -->

Here is a graduation programme, in which the main content section is defined by the use of the main element. Note in this example the main element contains a nav element consisting of links to sub sections of the main content.

<html lang="en">
  <head>
    <title>Graduation Ceremony Summer 2022</title>
  </head>
  <body>

    <header>The Lawson Academy:
      <nav>
        <ul>
          <li><a href="courses.html">Courses</a></li>
          <li><a href="fees.html">Fees</a></li>
          <li><a>Graduation</a></li>
        </ul>
      </nav>
    </header>

    <main>
      <h1>Graduation</h1>
      <nav>
        <ul>
          <li><a href="#ceremony">Ceremony</a></li>
          <li><a href="#graduates">Graduates</a></li>
          <li><a href="#awards">Awards</a></li>
        </ul>
      </nav>

      <h2 id="ceremony">Ceremony</h2>
      <p>Opening Procession</p>
      <p>Speech by Valedictorian</p>
      <p>Speech by Class President</p>
      <p>Presentation of Diplomas</p>
      <p>Closing Speech by Headteacher</p>

      <h2 id="graduates">Graduates</h2>
      <ul>
        <li>Eileen Williams</li>
        <li>Andy Maseyk</li>
        <li>Blanca Sainz Garcia</li>
        <li>Clara Faulkner</li>
        <li>Gez Lemon</li>
        <li>Eloisa Faulkner</li>
      </ul>

      <h2 id="awards">Awards</h2>
      <ul>
        <li>Clara Faulkner</li>
        <li>Eloisa Faulkner</li>
        <li>Blanca Sainz Garcia</li>
      </ul>
    </main>

    <footer> Copyright 2012 B.lawson</footer>
  </body>
</html>

In the next example, both the header and the footer are outside the main element because they are generic to the website and not specific to main's content.

<!DOCTYPE html>
<html lang="en">

  <head>
    <title>Great Dogs for Families</title>
  </head>

  <body>

    <header>
      <h1>The Border Terrier</h1>
      <nav>
        <ul>
          <li><a href="index.html">Home</a></li>
          <li><a href="about.html">About</a></li>
          <li><a href="health.html">Health</a></li>
        </ul>
      </nav>
    </header>
    <main>
      <h2>Welcome!</h2>
      <p>This site is all about the Border Terrier, the best breed of dog that there is!</p>
    </main>
    <footer>
      <small>Copyright © <time datetime="2013">2013</time> by I. Devlin</small>
    </footer>

  </body>

</html>

Here, the same generic header and footer elements remain outside main, but there is an additional header element within the main element as its content is relevant to the content within main because it contains a relevant heading and in-page navigation. The in-page navigation is repeated within a footer which is again within the main element.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Great Dogs for Families</title>
  </head>
  <body>

    <header>
      <h1>The Border Terrier</h1>
      <nav>
        <ul>
          <li><a href="index.html">Home</a></li>
          <li><a href="about.html">About</a></li>
          <li><a href="health.html">Health</a></li>
        </ul>
      </nav>
    </header>
    <main>
      <section>
        <header>
          <h2>About</h2>
          <nav>
            <ul>
              <li><a href="#basic">Basic</a></li>
              <li><a href="#app">Appearance</a></li>
              <li><a href="#temp">Temperament</a></li>
            </ul>
          </nav>
        </header>
        <section id="basic">
          <h3>Basic Information</h3>
          <p>The Border Terrier is a small, rough-coated breed of dog of the terrier group, originally bred as fox and vermin hunters. [...]</p>
        </section>
        <section id="app">
          <h3>Appearance</h3>
          <p>Identifiable by their otter-shaped heads, Border Terriers have a broad skull and short (although many be fairly long), strong muzzle with a scissors bite. [...]</p>
        </section>
        <section id="temp">
          <h3>Temperament</h3>
          <p>Though sometimes stubborn and strong willed, border terriers are, on the whole very even tempered, and are friendly and rarely aggressive. [...] </p>
        </section>
        <footer>
          <a href="#basic">Basic</a> -
          <a href="#app">Appearance</a> -
          <a href="#temp">Temperament</a>
        </footer>
      </section>
    </main>
    <footer>
      <small>Copyright © <time datetime="2013">2013</time> by I. Devlin</small>
    </footer>

  </body>
</html>

This example is largely the same as the previous one except that it includes an aside. The content of the aside is considered to be relevant to the content within the main element, which is all about the Border Terrier, so the aside is placed within the main element.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Great Dogs for Families</title>
  </head>
  <body>

    <header>
      <h1>The Border Terrier</h1>
      <nav>
        <ul>
          <li><a href="index.html">Home</a></li>
          <li><a href="about.html">About</a></li>
          <li><a href="health.html">Health</a></li>
        </ul>
      </nav>
    </header>
    <main>
      <section>
        <header>
          <h2>About</h2>
          <nav>
            <ul>
              <li><a href="#basic">Basic</a></li>
              <li><a href="#app">Appearance</a></li>
              <li><a href="#temp">Temperament</a></li>
            </ul>
          </nav>
        </header>
        <section id="basic">
          <h3>Basic Information</h3>
          <p>The Border Terrier is a small, rough-coated breed of dog of the terrier group, originally bred as fox and vermin hunters. [...]</p>
        </section>
        <section id="app">
          <h3>Appearance</h3>
          <p>Identifiable by their otter-shaped heads, Border Terriers have a broad skull and short (although many be fairly long), strong muzzle with a scissors bite. [...]</p>
        </section>
        <section id="temp">
          <h3>Temperament</h3>
          <p>Though sometimes stubborn and strong willed, border terriers are, on the whole very even tempered, and are friendly and rarely aggressive. [...] </p>
        </section>
        <aside>
          <h3>History</h3>
          <p>The Border Terrier originates in, and takes its name from the Scottish borders. [...] </p>
        </aside>
        <footer>
          <a href="#basic">Basic</a> -
          <a href="#app">Appearance</a> -
          <a href="#temp">Temperament</a>
        </footer>
      </section>
    </main>
    <footer>
      <small>Copyright © <time datetime="2013">2013</time> by I. Devlin</small>
    </footer>

  </body>
</html>

In the following example, two aside elements containg adverts have been placed outside the main element as their content is not specific to the content within main. These asides could be on any page, as they are as generic as the header and footer shown.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Great Dogs for Families</title>
  </head>
  <body>

    <header>
      <h1>The Border Terrier</h1>
      <nav>
        <ul>
          <li><a href="index.html">Home</a></li>
          <li><a href="about.html">About</a></li>
          <li><a href="health.html">Health</a></li>
        </ul>
      </nav>
    </header>
    <main>
      <h2>Welcome!</h2>
      <p>This site is all about the Border Terrier, the best breed of dog
      that there is!</p>
    </main>
    <aside class="advert">
      <h2>Border Farm Breeders</h2>
      <p>We are a certified breeder of Border Terriers, contact us at...</p>
    </aside>
    <aside class="advert">
      <h2>Grumpy’s Pet Shop</h2>
      <p>Get all your pet’s needs at our shop!</p>
    </aside>

    <footer>
      <small>Copyright © <time datetime="2013">2013</time> by I. Devlin</small>
    </footer>

  </body>
</html>

4.4.15. The `div` element

Flow content.

Palpable content.

Where flow content is expected.

As a child of a dl element.

If the element is a child of a dl element: one or more dt elements followed by one or more dd elements, optionally intermixed with script-supporting elements.

If the element is not a child of a dl element: Flow content.

Neither tag is omissible

Any role value.

Any aria-* attributes applicable to the default or allowed roles.