W3C

HTML 5.2

Editor’s Draft,

4.4. Grouping content

4.4.1. The p element

Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Phrasing content.
Tag omission in text/html:
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, menu, 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.
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:
interface HTMLParagraphElement : HTMLElement {};

The p element represents a paragraph.

While paragraphs are usually represented in visual media by blocks of text that are physically separated from adjacent blocks through blank lines, a style sheet or user agent would be equally justified in presenting 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>
<fieldset>
  <legend>Personal information</legend>
  <p>
    <label>Name: <input name="n"></label>
    <label><input name="anon" type="checkbox"> Hide from other users</label>
  </p>
  <p><label>Address: <textarea name="a"></textarea></label></p>
</fieldset>
<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 p element should not be used when a more specific element is more appropriate.

The following example is technically correct:
<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>
List elements (in particular, ol and ul elements) cannot be children of p elements. When a sentence contains a bulleted list, therefore, one might wonder how it should be marked up.
For instance, this fantastic sentence has bullets relating to
  • wizards,

  • faster-than-light travel, and

  • telepathy,

and is further discussed below.

The solution is to realize that a paragraph, in HTML terms, is not a logical concept, but a structural one. In the fantastic example above, there are actually five paragraphs as defined by this specification: 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>faster-than-light travel, and
  <li>telepathy,
</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 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>faster-than-light travel, and
    <li>telepathy,
  </ul>
and is further discussed below.</div>

This example still has five structural paragraphs, but now the author can style just the div instead of having to consider each part of the example separately.

4.4.2. The hr element

Categories:
Flow content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
Allowed ARIA role attribute values:
separator (default - do not set) or presentation.
Allowed ARIA state and property attributes:
Global aria-* attributes
Any aria-* attributes applicable to the allowed roles.
DOM interface:
interface HTMLHRElement : HTMLElement {};

The hr element represents a paragraph-level thematic break, e.g., 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 Pandora’s Star by Peter F. Hamilton shows two paragraphs that precede 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>Dudley was ninety-two, in his second life, and fast approaching
time for another rejuvenation. Despite his body having the physical
age of a standard fifty-year-old, the prospect of a long degrading
campaign within academia was one he regarded with dread. For a
supposedly advanced civilization, the Intersolar Commonwealth could be
appallingly backward at times, not to mention cruel.</p>
<p><i>Maybe it won’t be that bad</i>, he told himself. The lie was
comforting enough to get him through the rest of the night’s
shift.</p>
<hr>
<p>The Carlton AllLander drove Dudley home just after dawn. Like the
astronomer, the vehicle was old and worn, but perfectly capable of
doing its job. It had a cheap diesel engine, common enough on a
semi-frontier world like Gralmond, although its drive array was a
thoroughly modern photoneural processor. With its high suspension and
deep-tread tyres it could plough along the dirt track to the
observatory in all weather and seasons, including the metre-deep snow
of Gralmond’s winters.</p>

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

4.4.3. The pre element

Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Phrasing content.
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:
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:

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.

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.4. The blockquote 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.
Tag omission in text/html:
Neither tag is omissible
Content attributes:
Global attributes
cite - Link to the source of the quotation.
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:
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. 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>He began his list of "lessons" with the following:</p>
<blockquote>One should never assume that his side of
the issue will be recognized, let alone that it will
be conceded to have merits.</blockquote>
<p>He continued with a number of similar points, ending with:</p>
<blockquote>Finally, one should be prepared for the threat
of breakdown in negotiations at any given moment and not
be cowed by the possibility.</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.5. The ol element

Categories:
Flow content.
If the element’s children include at least one li element: Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Zero or more li and script-supporting elements.
Tag omission in text/html:
Neither tag is omissible
Content attributes:
Global attributes
reversed - Number the list backwards.
start - Ordinal value of the first item
type - Kind of list marker.
Allowed ARIA role attribute values:
list role (default - do not set), directory, group, listbox, menu, menubar, presentation, radiogroup, tablist, toolbar or tree.
Allowed ARIA state and property attributes:
Global aria-* attributes
Any aria-* attributes applicable to the allowed roles.
DOM interface:
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>United Kingdom
  <li>United States
  <li>Norway
</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>Switzerland
  <li>United States
  <li>Norway
</ol>

4.4.6. The ul element

Categories:
Flow content.
If the element’s children include at least one li element: Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Zero or more li and script-supporting elements.
Tag omission in text/html:
Neither tag is omissible
Content attributes:
Global attributes
Allowed ARIA role attribute values:
list role (default - do not set), directory, group, listbox, menu, menubar, presentation, radiogroup, tablist, toolbar or tree.
Allowed ARIA state and property attributes:
Global aria-* attributes
Any aria-* attributes applicable to the allowed roles.
DOM interface:
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>Switzerland
  <li>United Kingdom
  <li>United States
</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>Norway
  <li>United Kingdom
  <li>United States
</ul>

4.4.7. The li element

Categories:
None.
Contexts in which this element can be used:
Inside ol elements.
Inside ul elements.
Inside menu elements whose type attribute is in the toolbar state.
Content model:
Flow content.
Tag omission in text/html:
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.
Content attributes:
Global attributes
If the element is not a child of an ul or menu element: value
Allowed ARIA role attribute values:
listitem role (default - do not set), menuitem, menuitemcheckbox, menuitemradio, option, presentation, radio, separator, tab or treeitem.
Allowed ARIA state and property attributes:
Global aria-* attributes
Any aria-* attributes applicable to the allowed roles.
DOM interface:
interface HTMLLIElement : HTMLElement {
  attribute long value;
};

The li element represents a list item. If its parent element is an ol, ul, or menu element, 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="sh">Црна мачка, бели мачор</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="sh">Црна мачка, бели мачор</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.8. The dl element

Categories:
Flow content.
If the element’s children include at least one name-value group: Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
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.
Tag omission in text/html:
Neither tag is omissible
Content attributes:
Global attributes
Allowed ARIA role attribute values:
list role (default - do not set), directory, group, listbox, menu, menubar, presentation, radiogroup, tablist, toolbar or tree.
Allowed ARIA state and property attributes:
Global aria-* attributes
Any aria-* attributes applicable to the allowed roles.
DOM interface:
interface HTMLDListElement : HTMLElement {};

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).

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 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.

If a dl element has one or more non-whitespace text node children, or has children that are neither dt or dd elements, then all such text nodes and elements as well as their descendants (including any dt and dd elements) do not form part of any term-description group within the dl.

If a dl element has one or more dt element children, but no dd element children, then it consists of one group with terms but no descriptions.

If a dl element has one or more dd element children, but no dt element children, it consists of one group with descriptions but no terms.

If a dd element is the first child of a dl element (excepting a script-supporting element), the first group has no associated term.

If a dt element is the last child of a dl element (excepting a script-supporting element), the last group has no associated descriptions.

Note: 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.9. 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:
None.
Allowed ARIA state and property attributes:
Global aria-* attributes
Any aria-* attributes None
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 the definition for a term. The dfn element should be used to represent a definition.

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.10. 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:
None
Allowed ARIA state and property attributes:
Global aria-* attributes
Any aria-* attributes applicable to the 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.11. 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:
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 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:

<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.

<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.
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.12. 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:
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 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.13. The main element

Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
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) or presentation.
Allowed ARIA state and property attributes:
Global aria-* attributes
Any aria-* attributes applicable to the allowed roles.
DOM interface:
Uses HTMLElement

The main element represents the main content of the body of a document or application.

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

The main content area of a document includes content that is unique to that document and excludes content that is repeated across a set of documents such as site navigation links, copyright information, site logos and banners and search forms (unless the document or application’s main function is that of a search form).

Authors must not include the main element as a descendant of an article, aside, footer, header or nav element.

The main element is not suitable for use to identify the main content areas of sub sections of a document or application. The simplest solution is to not mark up the main content of a sub section at all, and just leave it as implicit, but an author could use a §4.4 Grouping content or sectioning content element as appropriate.

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 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.

<!DOCTYPE html>
<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 Headmaster</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.14. The div element

Categories:
Flow content.
Palpable content.
Contexts in which this element can be used:
Where flow content is expected.
Content model:
Flow content.
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:
interface HTMLDivElement : HTMLElement {};

The div element has no special meaning at all. It represents its children. It can be used with the class, lang, and title attributes to mark up semantics common to a group of consecutive elements.

Authors are strongly encouraged to view the div element as an element of last resort, for when no other element is suitable. Use of more appropriate elements instead of the div element leads to better accessibility for readers and easier maintainability for authors.

For example, a blog post would be marked up using article, a chapter using section, a page’s navigation aids using nav, and a group of form controls using fieldset.

On the other hand, div elements can be useful for stylistic purposes or to wrap multiple paragraphs within a section that are all to be annotated in a similar way. In the following example, we see div elements used as a way to set the language of two paragraphs at once, instead of setting the language on the two paragraph elements separately:

<article lang="en-US">
  <h2>My use of language and my cats</h2>
  <p>My cat’s behavior hasn’t changed much since her absence, except
  that she plays her new physique to the neighbors regularly, in an
  attempt to get pets.</p>
  <div lang="en-GB">
  <p>My other cat, colored black and white, is a sweetie. He followed
  us to the pool today, walking down the pavement with us. Yesterday
  he apparently visited our neighbours. I wonder if he recognizes that
  their flat is a mirror image of ours.</p>
  <p>Hm, I just noticed that in the last paragraph I used British
  English. But I’m supposed to write in American English. So I
  shouldn’t say "pavement" or "flat" or "color"...</p>
  </div>
  <p>I should say "sidewalk" and "apartment" and "color"!</p>
</article>