The html element represents the root of an HTML document.
Authors are encouraged to specify a lang attribute on the root
html element, giving the document's language. This aids speech synthesis tools to
determine what pronunciations to use, translation tools to determine what rules to use, and so
forth.
The manifest attribute is part of the
legacy "offline Web applications" feature, which is in the process of being
removed from the Web platform. (This is a long process that takes many years.) Using the manifest attribute at this time is highly discouraged. Use
service workers instead. [SW]
The manifest attribute only has an effect during the early stages of document load.
Changing the attribute dynamically thus has no effect (and thus, no DOM API is provided for this
attribute).
The html element in the following example declares that the document's language
is English.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Swapping Songs</title>
</head>
<body>
<h1>Swapping Songs</h1>
<p>Tonight I swapped some of the songs I wrote with some friends, who
gave me some of the songs they wrote. I love sharing my music.</p>
</body>
</html>
If the document is an iframesrcdoc document or if title information is available from a higher-level protocol: Zero or more elements of metadata content, of which no more than one is a title element and no more than one is a base element.
Otherwise: One or more elements of metadata content, of which exactly one is a title element and no more than one is a base element.
The title element is a required child in most situations, but when a
higher-level protocol provides title information, e.g. in the Subject line of an e-mail when HTML
is used as an e-mail authoring format, the title element can be omitted.
The title element represents the document's title or name. Authors
should use titles that identify their documents even when they are used out of context, for
example in a user's history or bookmarks, or in search results. The document's title is often
different from its first heading, since the first heading does not have to stand alone when taken
out of context.
There must be no more than one title element per document.
If it's reasonable for the Document to have no title, then the
title element is probably not required. See the head element's content
model for a description of when the element is required.
Can be set, to replace the element's children with the given value.
The IDL attribute text must return the
child text content of the title element. On setting, it must act the
same way as the textContent IDL attribute.
Here are some examples of appropriate titles, contrasted with the top-level headings that
might be used on those same pages.
<title>Introduction to The Mating Rituals of Bees</title>
...
<h1>Introduction</h1>
<p>This companion guide to the highly successful
<cite>Introduction to Medieval Bee-Keeping</cite> book is...
The next page might be a part of the same site. Note how the title describes the subject
matter unambiguously, while the first heading assumes the reader knows what the context is and
therefore won't wonder if the dances are Salsa or Waltz:
<title>Dances used during bee mating rituals</title>
...
<h1>The Dances</h1>
The string to use as the document's title is given by the document.title IDL attribute.
User agents should use the document's title when referring to the document in their user
interface. When the contents of a title element are used in this way, the
directionality of that title element should be used to set the directionality
of the document's title in the user interface.
A base element, if it has an href attribute,
must come before any other elements in the tree that have attributes defined as taking URLs, except the html element (its manifest attribute isn't affected by base
elements).
If there are multiple base elements with href attributes, all but the first are ignored.
Let urlRecord be the result of parsing the
value of element's href content attribute with
document's fallback base URL, and document's character encoding. (Thus, the base
element isn't affected by itself.)
<!DOCTYPE html>
<html lang="en">
<head>
<title>This is an example for the <base> element</title>
<base href="https://www.example.com/news/index.html">
</head>
<body>
<p>Visit the <a href="archives.html">archives</a>.</p>
</body>
</html>
The link in the above example would be a link to "https://www.example.com/news/archives.html".
The link element allows authors to link their document to other resources.
The destination of the link(s) is given by the href attribute, which must be present and must contain a
valid non-empty URL potentially surrounded by spaces. If the href attribute is absent, then the element does not define a
link.
A link element must have either a rel attribute
or an itemprop attribute, but not both.
The types of link indicated (the relationships) are given by the value of the rel attribute, which, if present, must have a value that
is a set of space-separated tokens. The allowed keywords and
their meanings are defined in a later section. If the rel attribute is absent, has no keywords, or if none of the keywords
used are allowed according to the definitions in this specification, then the element does not
create any links.
The as attribute specifies the destination for a preload request for the resource
given by the href attribute. If the attribute is present, the
value must case-sensitively match one of the destination keywords. The default value is the empty
string. The attribute may be omitted. The attribute must not be specified on link
elements that do not have a rel attribute that contains the
preload keyword. User agents must implement the
processing model of the as attribute described in
Preload. [FETCH][PRELOAD]
If a link element has an itemprop attribute,
or has a rel attribute that contains only keywords that are
body-ok, then the element is said to be allowed in the body. This means
that the element can be used where phrasing content is expected.
If the rel attribute is used, the element can
only sometimes be used in the body of the page. When used with the itemprop attribute, the element can be used both in the
head element and in the body of the page, subject to the constraints of
the microdata model.
Two categories of links can be created using the link element: Links to external resources and hyperlinks. The link types section defines
whether a particular link type is an external resource or a hyperlink. One link
element can create multiple links (of which some might be external resource links and some might
be hyperlinks); exactly which and how many links are created depends on the keywords given in the
rel attribute. User agents must process the links on a per-link
basis, not a per-element basis.
Each link created for a link element is handled separately. For
instance, if there are two link elements with rel="stylesheet",
they each count as a separate external resource, and each is affected by its own attributes
independently. Similarly, if a single link element has a rel attribute with the value next stylesheet,
it creates both a hyperlink (for the next keyword) and
an external resource link (for the stylesheet
keyword), and they are affected by other attributes (such as media or title)
differently.
For example, the following link element creates two hyperlinks (to the same
page):
<link rel="author license" href="/about">
The two links created by this element are one whose semantic is that the target page has
information about the current page's author, and one whose semantic is that the target page has
information regarding the license under which the current page is provided.
The nonce attribute represents a
cryptographic nonce ("number used once") which can be used by Content Security Policy
to determine whether or not an external resource specified by the link will be loaded and applied
to the document. The value is text. [CSP]
The integrity attribute represents the integrity metadata for requests which this
element is responsible for. The value is text. The attribute must not be specified on
link elements that do not have a rel attribute
that contains the stylesheet keyword. [SRI]
The crossorigin attribute is a CORS
settings attribute. It is intended for use with external resource links.
The exact behavior for links to external resources depends on the exact relationship, as
defined for the relevant link type. Some of the attributes control whether or not the external
resource is to be applied (as defined below).
For external resources that are represented in the DOM (for example, style sheets), the DOM
representation must be made available (modulo cross-origin restrictions) even if the resource is
not applied. To obtain the resource, the user agent must
run the following steps:
If the href attribute's value is the empty string,
then abort these steps.
User agents may opt to only try to obtain such resources when they are needed, instead of
pro-actively fetching all the external resources that are not applied.
The semantics of the protocol used (e.g. HTTP) must be followed when fetching external
resources. (For example, redirects will be followed and 404 responses will cause the external
resource to not be applied.)
Once the attempts to obtain the resource and its critical subresources are
complete, the user agent must, if the loads were successful, queue a task to
fire an event named load
at the link element, or, if the resource or one of its critical
subresources failed to completely load for any reason (e.g. DNS error, HTTP 404 response, a
connection being prematurely closed, unsupported Content-Type), queue a task to fire an event named error at
the link element. Non-network errors in processing the resource or its subresources
(e.g. CSS parse errors, PNG decoding errors) are not failures for the purposes of this
paragraph.
The element must delay the load event of the element's node document until all the
attempts to obtain the resource and its critical subresources are complete.
(Resources that the user agent has not yet attempted to obtain, e.g. because it is waiting for the
resource to be needed, do not delay the load event.)
Interactive user agents may provide users with a means to follow the hyperlinks created using the link element, somewhere
within their user interface. The exact interface is not defined by this specification, but it
could include the following information (obtained from the element's attributes, again as defined
below), in some form or another (possibly simplified), for each hyperlink created with each
link element in the document:
The relationship between this document and the resource (given by the rel attribute)
The title of the resource (given by the title
attribute).
The address of the resource (given by the href
attribute).
The language of the resource (given by the hreflang
attribute).
The optimum media for the resource (given by the media
attribute).
User agents could also include other information, such as the type of the resource (as given by
the type attribute).
Hyperlinks created with the link element and its rel attribute apply to the whole document. This contrasts with the
rel attribute of a and area
elements, which indicates the type of a link whose context is given by the link's location within
the document.
The media attribute says which media the
resource applies to. The value must be a valid media query list.
If the link is a hyperlink then the media
attribute is purely advisory, and describes for which media the document in question was
designed.
However, if the link is an external resource link, then the media attribute is prescriptive. The user agent must apply the
external resource when the media attribute's value
matches the environment and the other relevant conditions apply, and must not apply
it otherwise.
The external resource might have further restrictions defined within that limit
its applicability. For example, a CSS style sheet might have some @media
blocks. This specification does not override such further restrictions or requirements.
The default, if the media attribute is
omitted, is "all", meaning that by default links apply to all media.
The type attribute gives the MIME
type of the linked resource. It is purely advisory. The value must be a valid MIME
type.
For external resource links, the type attribute is used as a hint to user agents so that they can
avoid fetching resources they do not support. If the attribute is present, then
the user agent must assume that the resource is of the given type (even if that is not a
valid MIME type, e.g. the empty string). If the attribute is omitted, but the
external resource link type has a default type defined, then the user agent must assume that the
resource is of that type. If the UA does not support the given MIME type for the
given link relationship, then the UA should not obtain
the resource; if the UA does support the given MIME type for the given link
relationship, then the UA should obtain the resource at
the appropriate time as specified for the external resource link's particular type.
If the attribute is omitted, and the external resource link type does not have a default type
defined, but the user agent would obtain the resource if
the type was known and supported, then the user agent should obtain the resource under the assumption that it will be
supported.
User agents must not consider the type attribute
authoritative — upon fetching the resource, user agents must not use the type attribute to determine its actual type. Only the actual type
(as defined in the next paragraph) is used to determine whether to apply the resource,
not the aforementioned assumed type.
If the external resource link type defines rules for processing
the resource's Content-Type metadata, then those rules apply.
Otherwise, if the resource is expected to be an image, user agents may apply the image sniffing rules, with the official
type being the type determined from the resource's Content-Type
metadata, and use the resulting computed type of the
resource as if it was the actual type.
Otherwise, if neither of these conditions apply or if the user agent opts not to apply the image
sniffing rules, then the user agent must use the resource's Content-Type metadata to determine the type of the resource. If there
is no type metadata, but the external resource link type has a default type defined, then the user
agent must assume that the resource is of that type.
Once the user agent has established the type of the resource, the user agent must apply the
resource if it is of a supported type and the other relevant conditions apply, and must ignore the
resource otherwise.
If a document contains style sheet links labeled as follows:
...then a compliant UA that supported only CSS style sheets would fetch the B and C files, and
skip the A file (since text/plain is not the MIME type for CSS style
sheets).
For files B and C, it would then check the actual types returned by the server. For those that
are sent as text/css, it would apply the styles, but for those labeled as
text/plain, or any other type, it would not.
If one of the two files was returned without a Content-Type metadata, or with a
syntactically incorrect type like Content-Type: "null", then the
default type for stylesheet links would kick in. Since that
default type is text/css, the style sheet would nonetheless be
applied.
The title attribute gives the title of the
link. With one exception, it is purely advisory. The value is text. The exception is for style
sheet links that are in a document tree, for which the title attribute defines CSS
style sheet sets.
The title attribute on link
elements differs from the global title attribute of most other
elements in that a link without a title does not inherit the title of the parent element: it
merely has no title.
The sizes attribute is used with the icon link type. The attribute must not be specified on link
elements that do not have a rel attribute that specifies the
icon keyword or the apple-touch-icon
keyword.
The color attribute is used with the mask-icon link type. The attribute must not be specified on link
elements that do not have a rel attribute that contains the
mask-icon keyword.
The value must be a string that matches the CSS <color> production, defining
a suggested color that user agents can use to customize the display of the icon that the user
sees when they pin your site.
This specification does not have any user agent requirements for the color attribute.
There is no reflecting IDL attribute for the color attribute, but this might be added later.
HTTP `Link` headers, if supported, must be assumed to come
before any links in the document, in the order that they were given in the HTTP message. These
headers are to be processed according to the rules given in the relevant specifications. [HTTP][WEBLINK]
Registration of relation types in HTTP `Link`
headers is distinct from HTML link types, and thus their semantics can be
different from same-named HTML types.
The IDL attributes href, rel, as,
media, hreflang, type, nonce,
integrity, sizes, and scope each must reflect the respective content
attributes of the same name.
The crossOrigin IDL attribute must
reflect the crossorigin content attribute.
The IDL attribute relList must reflect the rel content attribute.
The following example shows how you can specify versions of the page that use alternative
formats, are aimed at other languages, and that are intended for other media:
The meta element can represent document-level metadata with the name attribute, pragma directives with the http-equiv attribute, and the file's character encoding
declaration when an HTML document is serialized to string form (e.g. for transmission over
the network or for disk storage) with the charset
attribute.
If either name, http-equiv, or itemprop is
specified, then the content attribute must also be
specified. Otherwise, it must be omitted.
The charset attribute specifies the character
encoding used by the document. This is a character encoding declaration. If the
attribute is present in an XML document, its value must be an
ASCII case-insensitive match for the string "utf-8" (and the
document is therefore forced to use UTF-8 as its encoding).
The charset attribute on the
meta element has no effect in XML documents, and is only allowed in order to
facilitate migration to and from XML.
There must not be more than one meta element with a charset attribute per document.
The content attribute gives the value of the document metadata
or pragma directive when the element is used for those purposes. The allowed values depend on the
exact context, as described in subsequent sections of this specification.
If a meta element has a name
attribute, it sets document metadata. Document metadata is expressed in terms of name-value pairs,
the name attribute on the meta element giving the
name, and the content attribute on the same element giving
the value. The name specifies what aspect of metadata is being set; valid names and the meaning of
their values are described in the following sections. If a meta element has no content attribute, then the value part of the metadata name-value
pair is the empty string.
The name and content IDL attributes must reflect the
respective content attributes of the same name. The IDL attribute httpEquiv must reflect the content
attribute http-equiv.
4.2.5.1 Standard metadata names
This specification defines a few names for the name
attribute of the meta element.
The value must be a short free-form string giving the name of the Web application that the
page represents. If the page is not a Web application, the application-name metadata name must not be used.
Translations of the Web application's name may be given, using the lang attribute to specify the language of each name.
There must not be more than one meta element with a given language
and with its name attribute set to the value application-name per document.
User agents may use the application name in UI in preference to the page's
title, since the title might include status messages and the like relevant to the
status of the page at a particular moment in time instead of just being the name of the
application.
To find the application name to use given an ordered list of languages (e.g. British English,
American English, and English), user agents must run the following steps:
If there is a default language, and if it is not the same language
as any of the languages in languages, append it to languages.
Let winning language be the first language in languages for which there is a meta element in the
Document that has its name attribute set to
the value application-name and whose
language is the language in question.
If none of the languages have such a meta element, then abort these steps;
there's no given application name.
This algorithm would be used by a browser when it needs a name for the page, for
instance, to label a bookmark. The languages it would provide to the algorithm would be the
user's preferred languages.
author
The value must be a free-form string giving the name of one of the page's
authors.
description
The value must be a free-form string that describes the page. The value must be
appropriate for use in a directory of pages, e.g. in a search engine. There must not be more than
one meta element with its name attribute set to
the value description per document.
generator
The value must be a free-form string that identifies one of the software packages used to
generate the document. This value must not be used on pages whose markup is not generated by
software, e.g. pages whose markup was written by a user in a text editor.
Here is what a tool called "Frontweaver" could include in its output, in the page's
head element, to identify itself as the tool used to generate the page:
This page about typefaces on British motorways uses a meta element to specify
some keywords that users might use to look for the page:
<!DOCTYPE HTML>
<html lang="en-GB">
<head>
<title>Typefaces on UK motorways</title>
<meta name="keywords" content="british,type face,font,fonts,highway,highways">
</head>
<body>
...
Many search engines do not consider such keywords, because this feature has
historically been used unreliably and even misleadingly as a way to spam search engine results
in a way that is not helpful for users.
To obtain the list of keywords that the author has specified as applicable to the page, the
user agent must run the following steps:
Let keywords be an empty list.
For each meta element with a name
attribute and a content attribute and whose name attribute's value is keywords, run the following substeps:
Return keywords. This is the list of keywords that the author has
specified as applicable to the page.
User agents should not use this information when there is insufficient confidence in the
reliability of the value.
For instance, it would be reasonable for a content management system to use
the keyword information of pages within the system to populate the index of a site-specific
search engine, but a large-scale content aggregator that used this information would likely find
that certain users would try to game its ranking mechanism through the use of inappropriate
keywords.
The value must be a string that matches the CSS <color> production, defining
a suggested color that user agents should use to customize the display of the page or of the
surrounding user interface. For example, a browser might color the page's title bar with the
specified value, or use it as a color highlight in a tab bar or task switcher.
There must not be more than one meta element with its name attribute set to the value theme-color per document.
This standard itself uses "WHATWG green" as its theme color:
When using the theme color in UI, user agents may adjust it in implementation-specific ways
to make it more suitable for the UI in question. For example, if a user agent intends to use
the theme color as a background and display white text over it, it might use a darker variant of
the theme color in that part of the UI, to ensure adequate contrast.
4.2.5.2 Other metadata names
Anyone can create and use their own extensions to the
predefined set of metadata names. There is no requirement to register such extensions.
However, a new metadata name should not be created in any of the following cases:
If the name is for something expected to have processing requirements in user agents; in
that case it ought to be standardized.
Also, before creating and using a new metadata name, consulting the WHATWG Wiki MetaExtensions page is
encouraged — to avoid choosing a metadata name that's already in use, and to avoid duplicating the
purpose of any metadata names that are already in use, and to avoid new standardized names
clashing with your chosen name. [WHATWGWIKI]
Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time to add a metadata name.
New metadata names can be specified with the following information:
Keyword
The actual name being defined. The name should not be confusingly similar to any other
defined name (e.g. differing only in case).
Brief description
A short non-normative description of what the metadata name's meaning is, including the
format the value is required to be in.
Specification
A link to a more detailed description of the metadata name's semantics and requirements. It
could be another page on the Wiki, or a link to an external page.
Synonyms
A list of other names that have exactly the same processing requirements. Authors should
not use the names defined to be synonyms (they are only intended to allow user agents to support
legacy content). Anyone may remove synonyms that are not used in practice; only names that need to
be processed as synonyms for compatibility with legacy content are to be registered in this
way.
Status
One of the following:
Proposed
The name has not received wide peer review and approval. Someone has proposed it and is, or
soon will be, using it.
Ratified
The name has received wide peer review and approval. It has a specification that
unambiguously defines how to handle pages that use the name, including when they use it in
incorrect ways.
Discontinued
The metadata name has received wide peer review and it has been found wanting. Existing
pages are using this metadata name, but new pages should avoid it. The "brief description" and
"specification" entries will give details of what authors should use instead, if anything.
If a metadata name is found to be redundant with existing values, it should be removed and
listed as a synonym for the existing value.
If a metadata name is added in the "proposed" state for a period of a month or more without
being used or specified, then it may be removed from the WHATWG Wiki MetaExtensions page.
If a metadata name is added with the "proposed" status and found to be redundant with
existing values, it should be removed and listed as a synonym for the existing value. If a
metadata name is added with the "proposed" status and found to be harmful, then it should be
changed to "discontinued" status.
Anyone can change the status at any time, but should only do so in accordance with the
definitions above.
4.2.5.3 Pragma directives
When the http-equiv attribute is specified on a
meta element, the element is a pragma directive.
The http-equiv attribute is an enumerated
attribute. The following table lists the keywords defined for this attribute. The states
given in the first cell of the rows with keywords give the states to which those keywords map.
Some of the keywords are non-conforming, as noted in the last
column.
When a meta element is inserted
into the document, if its http-equiv attribute is
present and represents one of the above states, then the user agent must run the algorithm
appropriate for that state, as described in the following list:
Content language state
(http-equiv="content-language")
This feature is non-conforming. Authors are encouraged to use the lang attribute instead.
This pragma sets the pragma-set default language. Until such a pragma is
successfully processed, there is no pragma-set default language.
If the meta element has no content
attribute, then abort these steps.
If the element's content attribute contains a
U+002C COMMA character (,) then abort these steps.
Let input be the value of the element's content attribute.
Let position point at the first character of input.
If another meta element with an http-equiv attribute in the Refresh state has already been successfully
processed (i.e. when it was inserted the user agent processed it and reached the step labeled
end), then abort these steps.
If the meta element has no content
attribute, or if that attribute's value is the empty string, then abort these steps.
If position is past the end of input, jump to the step labeled
end.
If the character in input pointed to by position is not a U+003B
SEMICOLON character (;), a U+002C COMMA character (,), or ASCII whitespace, then
abort these steps.
If the character in input pointed to by position is a U+003B
SEMICOLON character (;), a U+002C COMMA character (,), then advance position to the
next character.
If position is past the end of input, jump to the step labeled
end.
Let url be equal to the substring of input from
the character at position to the end of the string.
If the character in input pointed to by position
is a U+0055 LATIN CAPITAL LETTER U character (U) or a U+0075 LATIN SMALL LETTER U character
(u), then advance position to the next character. Otherwise, jump to the step
labeled skip quotes.
If the character in input pointed to by position
is a U+0052 LATIN CAPITAL LETTER R character (R) or a U+0072 LATIN SMALL LETTER R character
(r), then advance position to the next character. Otherwise, jump to the step
labeled parse.
If the character in input pointed to by position
is s U+004C LATIN CAPITAL LETTER L character (L) or a U+006C LATIN SMALL LETTER L character
(l), then advance position to the next character. Otherwise, jump to the step
labeled parse.
If the character in input pointed to by position
is a U+003D EQUALS SIGN (=), then advance position to the next character. Otherwise,
jump to the step labeled parse.
Skip quotes: If the character in input pointed to by
position is either a U+0027 APOSTROPHE character (') or U+0022 QUOTATION MARK
character ("), then let quote be that character, and advance position to
the next character. Otherwise, let quote be the empty string.
Let url be equal to the substring of input from
the character at position to the end of the string.
If quote is not the empty string, and there is a character in url
equal to quote, then truncate url at that character, so that it and all
subsequent characters are removed.
Parse: Parseurl relative to
document. If that fails, abort these steps. Otherwise, let urlRecord be
the resulting URL record.
For the purposes of the previous paragraph, a refresh is said to have come due as soon as
the later of the following two conditions occurs:
At least time seconds have elapsed since document has
completely loaded, adjusted to take into account user or user agent
preferences.
At least time seconds have elapsed since the meta element was
inserted into the documentdocument, adjusted to take into account user or user agent preferences.
It is important to use document here, and not the
meta element's node document, as that might have changed between
the initial set of steps and the refresh coming due.
In addition, the user agent may, as with anything, inform the user of any and all aspects
of its operation, including the state of any timers, the destinations of any timed redirects,
and so forth.
a valid non-negative integer, followed by a U+003B SEMICOLON character
(;), followed by one or more ASCII whitespace, followed by a substring that is
an ASCII case-insensitive match for the string "URL",
followed by a U+003D EQUALS SIGN character (=), followed by a valid URL string
that does not start with a literal U+0027 APOSTROPHE (') or U+0022 QUOTATION MARK (")
character.
In the former case, the integer represents a number of seconds before the page is to be
reloaded; in the latter case the integer represents a number of seconds before the page is to be
replaced by the page at the given URL.
A news organization's front page could include the following markup in the page's
head element, to ensure that the page automatically reloads from the server every
five minutes:
<meta http-equiv="Refresh" content="300">
A sequence of pages could be used as an automated slide show by making each page refresh to
the next page in the sequence, using markup such as the following:
A page might choose to mitigate the risk of cross-site scripting attacks by preventing the
execution of inline JavaScript, as well as blocking all plugin content, using a policy such
as the following:
Such extensions must use a name that is identical to an HTTP header registered in the Permanent
Message Header Field Registry, and must have behavior identical to that described for the HTTP
header. [IANAPERMHEADERS]
Pragma directives corresponding to headers describing metadata, or not requiring specific user
agent processing, must not be registered; instead, use metadata names. Pragma directives corresponding to headers
that affect the HTTP processing model (e.g. caching) must not be registered, as they would result
in HTTP-level behavior being different for user agents that implement HTML than for user agents
that do not.
Anyone is free to edit the WHATWG Wiki PragmaExtensions page at any time to add a pragma
directive satisfying these conditions. Such registrations must specify the following
information:
Keyword
The actual name being defined. The name must match a previously-registered HTTP name with
the same requirements.
Brief description
A short non-normative description of the purpose of the pragma directive.
Specification
A link to the specification defining the corresponding HTTP header.
Conformance checkers must use the information given on the WHATWG Wiki PragmaExtensions page to
establish if a value is allowed or not: values defined in this specification or listed on the
aforementioned page must be accepted, whereas values not listed in either this specification or on
the aforementioned page must be rejected as invalid. Conformance checkers may cache this
information (e.g. for performance reasons or to avoid the use of unreliable network
connectivity).
4.2.5.5 Specifying the document's character encoding
A character encoding declaration is required (either in the Content-Type metadata or explicitly in the file) even when all
characters are in the ASCII range, because a character encoding is needed to process non-ASCII
characters entered by the user in forms, in URLs generated by scripts, and so forth.
Authors should use UTF-8. Conformance checkers may advise authors against using
legacy encodings. [ENCODING]
Authoring tools should default to using UTF-8 for newly-created documents. [ENCODING]
Authors must not use encodings that are not defined in the WHATWG Encoding standard.
Additionally, authors should not use ISO-2022-JP. [ENCODING]
Some encodings that are not defined in the WHATWG Encoding standard use bytes in
the range 0x20 to 0x7E, inclusive, to encode characters other than the corresponding characters in
the range U+0020 to U+007E, inclusive, and represent a potential security vulnerability: a user
agent might end up interpreting supposedly benign plain text content as HTML tags and
JavaScript.
Using non-UTF-8 encodings can have unexpected results on form submission and URL
encodings, which use the document's character encoding by default.
In XML, the XML declaration should be used for inline character encoding information, if
necessary.
In HTML, to declare that the character encoding is UTF-8, the author could
include the following markup near the top of the document (in the head element):
<meta charset="utf-8">
In XML, the XML declaration would be used instead, at the very top of the markup:
The style element allows authors to embed style information in their documents.
The style element is one of several inputs to the styling processing
model. The element does not represent content for the
user.
The type attribute gives the styling language.
If the attribute is present, its value must be a valid MIME type that designates a
styling language. The charset parameter must not be specified. The default
value for the type attribute, which is used if the attribute
is absent, is "text/css". [RFC2318]
When examining types
to determine if they support the language, user agents must not ignore unknown MIME parameters
— types with unknown parameters must be assumed to be unsupported. The charset parameter must be treated as an unknown parameter for the purpose of
comparing MIME types here.
The media attribute says which media the
styles apply to. The value must be a valid media query list. The user
agent must apply the styles when the media attribute's
value matches the environment and the other relevant conditions apply, and must not
apply them otherwise.
The styles might be further limited in scope, e.g. in CSS with the use of @media blocks. This specification does not override such further restrictions or
requirements.
The default, if the media
attribute is omitted, is "all", meaning that by default styles apply to all
media.
The nonce attribute represents a
cryptographic nonce ("number used once") which can be used by Content Security Policy
to determine whether or not the style specified by an element will be applied to the document. The
value is text. [CSP]
The title attribute on style
elements, like the title attribute on link
elements, differs from the global title attribute in that a
style block without a title does not inherit the title of the parent element: it
merely has no title.
The textContent of a style element must match the style production in the following ABNF, the character set for which is Unicode. [ABNF]
style = no-c-start *( c-start no-c-end c-end no-c-start )
no-c-start = < any string that doesn't contain a substring that matches c-start >
c-start = "<!--"
no-c-end = < any string that doesn't contain a substring that matches c-end >
c-end = "-->"
The user agent must run the update a style block
algorithm that applies for the style sheet language specified by the style
element's type attribute, passing it the element's
style data, whenever one of the following conditions occur:
For styling languages that consist of pure text (as opposed to XML), a style
element's style data is the child text content of the style
element. For XML-based styling languages, the style data consists of all the child
nodes of the style element.
This is a reference to the (possibly absent at this time) attribute, rather
than a copy of the attribute's current value. The CSSOM specification defines what happens
when the attribute is dynamically set, changed, or removed.
This specification does not define any other styling language's update a style block algorithm.
Once the attempts to obtain the style sheet's critical subresources, if any, are
complete, or, if the style sheet has no critical subresources, once the style sheet
has been parsed and processed, the user agent must, if the loads were successful or there were
none, queue a task to fire an event named
load at the style element, or, if one of the style
sheet's critical subresources failed to completely load for any reason (e.g. DNS
error, HTTP 404 response, a connection being prematurely closed, unsupported Content-Type),
queue a task to fire an event named error at the style element. Non-network errors in
processing the style sheet or its subresources (e.g. CSS parse errors, PNG decoding errors) are
not failures for the purposes of this paragraph.
This specification does not specify a style system, but CSS is expected to be
supported by most Web browsers. [CSS]
The media, nonce, and type IDL attributes must reflect the respective
content attributes of the same name.
The LinkStyle interface is also implemented by this element. [CSSOM]
The following document has its stress emphasis styled as bright red text rather than italics
text, while leaving titles of works and Latin words in their default italics. It shows how using
appropriate elements enables easier restyling of documents.
<!DOCTYPE html>
<html lang="en-US">
<head>
<title>My favorite book</title>
<style>
body { color: black; background: white; }
em { font-style: normal; color: red; }
</style>
</head>
<body>
<p>My <em>favorite</em> book of all time has <em>got</em> to be
<cite>A Cat's Life</cite>. It is a book by P. Rahmel that talks
about the <i lang="la">Felis Catus</i> in modern human society.</p>
</body>
</html>
4.2.7 Interactions of styling and scripting
Style sheets, whether added by a link element, a style element, an
<?xml-stylesheet?> PI, an HTTP `Link` header, or
some other mechanism, have a style sheet ready flag, which is initially unset.
When a style sheet is ready to be applied, its style sheet ready flag must be set.
If the style sheet referenced no other resources (e.g. it was an internal style sheet given by a
style element with no @import rules), then the style rules must
be immediately made available to script; otherwise, the style rules must only be made available
to script once the event loop reaches its update the rendering step.
A style sheet in the context of the Document of an HTML parser or
XML parser is said to be a style sheet that is blocking scripts if the
element was created by that Document's parser, and the element is either a
style element or a link element that was an external resource link that contributes to the styling processing
model when the element was created by the parser, and the element's style sheet was enabled
when the element was created by the parser, and the element's style sheet ready flag
is not yet set, and, the last time the event loop reached step 1,
the element's root was that Document, and the user agent hasn't given up
on that particular style sheet yet. A user agent may give up on a style sheet at any time.
Giving up on a style sheet before the style sheet loads, if the style sheet
eventually does still load, means that the script might end up operating with incorrect
information. For example, if a style sheet sets the color of an element to green, but a script
that inspects the resulting style is executed before the sheet is loaded, the script will find
that the element is black (or whatever the default color is), and might thus make poor choices
(e.g. deciding to use black as the color elsewhere on the page, instead of green). Implementors
have to balance the likelihood of a script using incorrect information with the performance impact
of doing nothing while waiting for a slow network request to finish.
Support: html5semanticChrome for Android56+Chrome26+UC Browser for Android (limited)11+iOS Safari7.0+Firefox21+IE (limited)9+Samsung Internet4+Opera Mini (limited)all+Android Browser4.4+Safari6.1+Edge12+Opera15+
The body element represents the main content of the document.
In conforming documents, there is only one body element. The document.body IDL attribute provides scripts with easy access to
a document's body element.
Some DOM operations (for example, parts of the drag and drop model)
are defined in terms of "the body element". This refers to a particular element in
the DOM, as per the definition of the term, and not any arbitrary body element.
The article element represents a complete, or self-contained,
composition in a document, page, application, or site and that is, in principle, independently
distributable or reusable, e.g. in syndication. This could be a forum post, a magazine or
newspaper article, a blog entry, a user-submitted comment, an interactive widget or gadget, or any
other independent item of content.
When article elements are nested, the inner article elements
represent articles that are in principle related to the contents of the outer article. For
instance, a blog entry on a site that accepts user-submitted comments could represent the comments
as article elements nested within the article element for the blog
entry.
Author information associated with an article element (q.v. the
address element) does not apply to nested article elements.
When used specifically with content to be redistributed in syndication, the
article element is similar in purpose to the entry element in
Atom. [ATOM]
The schema.org microdata vocabulary can be used to provide the publication date
for an article element, using one of the CreativeWork subtypes.
When the main content of the page (i.e. excluding footers, headers, navigation blocks, and
sidebars) is all one single self-contained composition, that content may be marked with an
article, but it is technically redundant in that case (since it's self-evident that
the page is a single composition, as it is a single document).
This example shows a blog post using the article element, with some schema.org
annotations:
<article itemscope itemtype="http://schema.org/BlogPosting">
<header>
<h1 itemprop="headline">The Very First Rule of Life</h1>
<p><time itemprop="datePublished" datetime="2009-10-09">3 days ago</time></p>
<link itemprop="url" href="?comments=0">
</header>
<p>If there's a microphone anywhere near you, assume it's hot and
sending whatever you're saying to the world. Seriously.</p>
<p>...</p>
<footer>
<a itemprop="discussionUrl" href="?comments=1">Show comments...</a>
</footer>
</article>
Here is that same blog post, but showing some of the comments:
<article itemscope itemtype="http://schema.org/BlogPosting">
<header>
<h1 itemprop="headline">The Very First Rule of Life</h1>
<p><time itemprop="datePublished" datetime="2009-10-09">3 days ago</time></p>
<link itemprop="url" href="?comments=0">
</header>
<p>If there's a microphone anywhere near you, assume it's hot and
sending whatever you're saying to the world. Seriously.</p>
<p>...</p>
<section>
<h1>Comments</h1>
<article itemprop="comment" itemscope itemtype="http://schema.org/UserComments" id="c1">
<link itemprop="url" href="#c1">
<footer>
<p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">George Washington</span>
</span></p>
<p><time itemprop="commentTime" datetime="2009-10-10">15 minutes ago</time></p>
</footer>
<p>Yeah! Especially when talking about your lobbyist friends!</p>
</article>
<article itemprop="comment" itemscope itemtype="http://schema.org/UserComments" id="c2">
<link itemprop="url" href="#c2">
<footer>
<p>Posted by: <span itemprop="creator" itemscope itemtype="http://schema.org/Person">
<span itemprop="name">George Hammond</span>
</span></p>
<p><time itemprop="commentTime" datetime="2009-10-10">5 minutes ago</time></p>
</footer>
<p>Hey, you have the same first name as me.</p>
</article>
</section>
</article>
Notice the use of footer to give the information for each comment (such as who
wrote it and when): the footer element can appear at the start of its
section when appropriate, such as in this case. (Using header in this case wouldn't
be wrong either; it's mostly a matter of authoring preference.)
In this example, article elements are used to host widgets on a portal page. The
widgets are implemented as customized built-in
elements in order to get specific styling and scripted behavior.
The section element represents a generic section of a document or
application. A section, in this context, is a thematic grouping of content, typically with a
heading.
Examples of sections would be chapters, the various tabbed pages in a tabbed
dialog box, or the numbered sections of a thesis. A Web site's home page could be split into
sections for an introduction, news items, and contact information.
Authors are encouraged to use the article element instead of the
section element when it would make sense to syndicate the contents of the
element.
The section element is not a generic
container element. When an element is needed only for styling purposes or as a convenience for
scripting, authors are encouraged to use the div element instead. A general rule is
that the section element is appropriate only if the element's contents would be
listed explicitly in the document's outline.
In the following example, we see an article (part of a larger Web page) about apples,
containing two short sections.
<article>
<hgroup>
<h1>Apples</h1>
<h2>Tasty, delicious fruit!</h2>
</hgroup>
<p>The apple is the pomaceous fruit of the apple tree.</p>
<section>
<h1>Red Delicious</h1>
<p>These bright red apples are the most common found in many
supermarkets.</p>
</section>
<section>
<h1>Granny Smith</h1>
<p>These juicy, green apples make a great filling for
apple pies.</p>
</section>
</article>
Notice how the use of section means that the author can use h1
elements throughout, without having to worry about whether a particular section is at the top
level, the second level, the third level, and so on.
Here is a graduation programme with two sections, one for the list of people graduating, and
one for the description of the ceremony. (The markup in this example features an uncommon style
sometimes used to minimize the amount of inter-element whitespace.)
In this example, a book author has marked up some sections as chapters and some as appendices,
and uses CSS to style the headers in these two classes of section differently.
<style>
section { border: double medium; margin: 2em; }
section.chapter h1 { font: 2em Roboto, Helvetica Neue, sans-serif; }
section.appendix h1 { font: small-caps 2em Roboto, Helvetica Neue, sans-serif; }
</style>
<header>
<hgroup>
<h1>My Book</h1>
<h2>A sample with not much content</h2>
</hgroup>
<p><small>Published by Dummy Publicorp Ltd.</small></p>
</header>
<section class="chapter">
<h1>My First Chapter</h1>
<p>This is the first of my chapters. It doesn't say much.</p>
<p>But it has two paragraphs!</p>
</section>
<section class="chapter">
<h1>It Continues: The Second Chapter</h1>
<p>Bla dee bla, dee bla dee bla. Boom.</p>
</section>
<section class="chapter">
<h1>Chapter Three: A Further Example</h1>
<p>It's not like a battle between brightness and earthtones would go
unnoticed.</p>
<p>But it might ruin my story.</p>
</section>
<section class="appendix">
<h1>Appendix A: Overview of Examples</h1>
<p>These are demonstrations.</p>
</section>
<section class="appendix">
<h1>Appendix B: Some Closing Remarks</h1>
<p>Hopefully this long example shows that you <em>can</em> style
sections, so long as they are used to indicate actual sections.</p>
</section>
The nav element represents a section of a page that links to other
pages or to parts within the page: a section with navigation links.
Not all groups of links on a page need to be in a nav element —
the element is primarily intended for sections that consist of major navigation blocks. In
particular, it is common for footers to have a short list of links to various pages of a site,
such as the terms of service, the home page, and a copyright page. The footer element
alone is sufficient for such cases; while a nav element can be used in such cases, it
is usually unnecessary.
User agents (such as screen readers) that are targeted at users who can benefit
from navigation information being omitted in the initial rendering, or who can benefit from
navigation information being immediately available, can use this element as a way to determine
what content on the page to initially skip or provide on request (or both).
In the following example, there are two nav elements, one for primary navigation
around the site, and one for secondary navigation around the page itself.
Notice the main elements being used to wrap all the contents of the page other
than the header and footer, and all the contents of the blog entry other than its header and
footer.
You can also see microdata annotations in the above example that use the schema.org vocabulary
to provide the publication date and other metadata about the blog post.
A nav element doesn't have to contain a list, it can contain other kinds of
content as well. In this navigation block, links are provided in prose:
<nav>
<h1>Navigation</h1>
<p>You are on my home page. To the north lies <a href="/blog">my
blog</a>, from whence the sounds of battle can be heard. To the east
you can see a large mountain, upon which many <a
href="/school">school papers</a> are littered. Far up thus mountain
you can spy a little figure who appears to be me, desperately
scribbling a <a href="/school/thesis">thesis</a>.</p>
<p>To the west are several exits. One fun-looking exit is labeled <a
href="https://games.example.com/">"games"</a>. Another more
boring-looking exit is labeled <a
href="https://isp.example.net/">ISP™</a>.</p>
<p>To the south lies a dark and dank <a href="/about">contacts
page</a>. Cobwebs cover its disused entrance, and at one point you
see a rat run quickly out of the page.</p>
</nav>
In this example, nav is used in an e-mail application, to let the user switch
folders:
The aside element represents a section of a page that consists of
content that is tangentially related to the content around the aside element, and
which could be considered separate from that content. Such sections are often represented as
sidebars in printed typography.
The element can be used for typographical effects like pull quotes or sidebars, for
advertising, for groups of nav elements, and for other content that is considered
separate from the main content of the page.
It's not appropriate to use the aside element just for
parentheticals, since those are part of the main flow of the document.
The following example shows how an aside is used to mark up background material on Switzerland
in a much longer news story on Europe.
<aside>
<h1>Switzerland</h1>
<p>Switzerland, a land-locked country in the middle of geographic
Europe, has not joined the geopolitical European Union, though it is
a signatory to a number of European treaties.</p>
</aside>
The following example shows how an aside is used to mark up a pull quote in a longer
article.
...
<p>He later joined a large company, continuing on the same work.
<q>I love my job. People ask me what I do for fun when I'm not at
work. But I'm paid to do my hobby, so I never know what to
answer. Some people wonder what they would do if they didn't have to
work... but I know what I would do, because I was unemployed for a
year, and I filled that time doing exactly what I do now.</q></p>
<aside>
<q> People ask me what I do for fun when I'm not at work. But I'm
paid to do my hobby, so I never know what to answer. </q>
</aside>
<p>Of course his work — or should that be hobby? —
isn't his only passion. He also enjoys other pleasures.</p>
...
The following extract shows how aside can be used for blogrolls and other side
content on a blog:
<body>
<header>
<h1>My wonderful blog</h1>
<p>My tagline</p>
</header>
<aside>
<!-- this aside contains two sections that are tangentially related
to the page, namely, links to other blogs, and links to blog posts
from this blog -->
<nav>
<h1>My blogroll</h1>
<ul>
<li><a href="https://blog.example.com/">Example Blog</a>
</ul>
</nav>
<nav>
<h1>Archives</h1>
<ol reversed>
<li><a href="/last-post">My last post</a>
<li><a href="/first-post">My first post</a>
</ol>
</nav>
</aside>
<aside>
<!-- this aside is tangentially related to the page also, it
contains twitter messages from the blog author -->
<h1>Twitter Feed</h1>
<blockquote cite="https://twitter.example.net/t31351234">
I'm on vacation, writing my blog.
</blockquote>
<blockquote cite="https://twitter.example.net/t31219752">
I'm going to go on vacation soon.
</blockquote>
</aside>
<article>
<!-- this is a blog post -->
<h1>My last post</h1>
<p>This is my last post.</p>
<footer>
<p><a href="/last-post" rel=bookmark>Permalink</a>
</footer>
</article>
<article>
<!-- this is also a blog post -->
<h1>My first post</h1>
<p>This is my first post.</p>
<aside>
<!-- this aside is about the blog post, since it's inside the
<article> element; it would be wrong, for instance, to put the
blogroll here, since the blogroll isn't really related to this post
specifically, only to the page as a whole -->
<h1>Posting</h1>
<p>While I'm thinking about it, I wanted to say something about
posting. Posting is fun!</p>
</aside>
<footer>
<p><a href="/first-post" rel=bookmark>Permalink</a>
</footer>
</article>
<footer>
<nav>
<a href="/archives">Archives</a> —
<a href="/about">About me</a> —
<a href="/copyright">Copyright</a>
</nav>
</footer>
</body>
These elements represent headings for their sections.
The semantics and meaning of these elements are defined in the section on headings and
sections.
These elements have a rank given by the number in their name. The h1
element is said to have the highest rank, the h6 element has the lowest rank, and two
elements with the same name have equal rank.
As far as their respective document outlines (their heading and section structures) are
concerned, these two snippets are semantically equivalent:
<body>
<h1>Let's call it a draw(ing surface)</h1>
<h2>Diving in</h2>
<h2>Simple shapes</h2>
<h2>Canvas coordinates</h2>
<h3>Canvas coordinates diagram</h3>
<h2>Paths</h2>
</body>
Authors might prefer the former style for its terseness, or the latter style for its
convenience in the face of heavy editing; which is best is purely an issue of preferred authoring
style.
The two styles can be combined, for compatibility with legacy tools while still
future-proofing for when that compatibility is no longer needed. This third snippet again has the
same outline as the previous two:
The hgroup element represents the heading of a section, which
consists of all the h1–h6 element children of the
hgroup element. The element is used to group a set of
h1–h6 elements when the heading has multiple levels, such as
subheadings, alternative titles, or taglines.
The rank of an hgroup element is the rank of the highest-ranked
h1–h6 element descendant of the hgroup element, if
there are any such elements, or otherwise the same as for an h1 element (the highest
rank). Other h1–h6 elements of heading content in the
hgroup element indicate subheadings or subtitles or (secondary) alternative
titles.
<hgroup>
<h1>The reality dysfunction</h1>
<h2>Space is not the only void</h2>
</hgroup>
<hgroup>
<h1>Dr. Strangelove</h1>
<h2>Or: How I Learned to Stop Worrying and Love the Bomb</h2>
</hgroup>
The point of using hgroup in these examples is to prevent the h2
element (which acts as a secondary title) from creating a separate section of its own in any
outline and to instead cause the contents of the h2 to be shown in
rendered output from the outline algorithm in some way to indicate that it is not
the title of a separate section but instead just a secondary title in a group of titles.
How a user agent exposes such multi-level headings in user interfaces (e.g. in tables of
contents or search results) is left open to implementors, as it is a user interface issue. The
first example above could be rendered as:
The reality dysfunction: Space is not the only void
Alternatively, it could look like this:
The reality dysfunction (Space is not the only void)
In interfaces where a title can be rendered on multiple lines, it could be rendered as
follows, maybe with the first line in a bigger font size:
The reality dysfunction
Space is not the only void
The following two examples show ways in which two h1 headings could be used
within an hgroup element to group the US and UK names for the same movie.
The first example above shows how the movie names might be grouped in a publication in the US,
with the US name The Avengers as the (primary) title, and the UK name Avengers
Assemble as the (secondary) alternative title. The second example above shows how the movie
names might be grouped in a publication in the UK, with the UK name as the (primary) title, and
the US name as the (secondary) alternative title.
In both cases it is important to note the use of the hgroup element to group the
two titles indicates that the titles are not equivalent; instead the first h1 gives
the (primary) title while the second gives the (secondary) alternative title. Even though both
the title and alternative title are marked up with h1 elements, in a rendered view
of output from the outline algorithm, the second h1 in the
hgroup will be shown in some way that clearly indicates it is secondary; for
example:
In a US publication:
The Avengers (Avengers Assemble)
In a UK publication:
Avengers Assemble (The Avengers)
In the following example, an hgroup element is used to mark up a two-level
heading in a wizard-style dialog box:
<dialog onclose="walletSetup.continue(this.returnValue)">
<hgroup>
<h1>Wallet Setup</h1>
<h2>Configure your Wallet funding source</h2>
</hgroup>
<p>Your Wallet can be used to buy wands at the merchant in town, to buy potions from travelling
salesmen you may find in the dungeons, and to pay for mercenaries.</p>
<p>We support two payment sources:</p>
<form method=dialog>
<fieldset oninput="this.getElementsByTagName('input')[0].checked = true">
<legend> <label> <input type=radio name=payment-type value=cc> Credit Card </label> </legend>
<p><label>Name on card: <input name=cc1 autocomplete="section-cc cc-name" placeholder="Y. Name"></label>
<p><label>Card number: <input name=cc2 inputmode=numeric autocomplete="section-cc cc-number" placeholder="6331 1019 9999 0016"></label>
<p><label>Expiry Date: <input name=cc3 type=month autocomplete="section-cc cc-exp" placeholder="2020-02"></label>
<p><label>Security Code: <input name=cc4 inputmode=numeric autocomplete="section-cc cc-csc" placeholder="246"></label>
</fieldset>
<fieldset oninput="this.getElementsByTagName('input')[0].checked = true">
<legend> <label> <input type=radio name=payment-type value=bank> Checking Account </label> </legend>
<p><label>Name on account: <input name=bank1 autocomplete="section-bank cc-name"></label>
<p><label>Routing number: <input name=bank2 inputmode=numeric></label>
<p><label>Account number: <input name=bank3 inputmode=numeric></label>
</fieldset>
<button type=submit value="back"> ← Back </button>
<button type=submit value="next"> Next → </button>
</form>
</dialog>
The header element represents a group of introductory or navigational
aids.
A header element is intended to usually contain the section's heading
(an h1–h6 element or an hgroup element), but this is
not required. The header element can also be used to wrap a section's table of
contents, a search form, or any relevant logos.
Here are some sample headers. This first one is for a game:
In this example, the page has a page heading given by the h1 element, and two
subsections whose headings are given by h2 elements. The content after the
header element is still part of the last subsection started in the
header element, because the header element doesn't take part in the
outline algorithm.
<body>
<header>
<h1>Little Green Guys With Guns</h1>
<nav>
<ul>
<li><a href="/games">Games</a>
<li><a href="/forum">Forum</a>
<li><a href="/download">Download</a>
</ul>
</nav>
<h2>Important News</h2> <!-- this starts a second subsection -->
<!-- this is part of the subsection entitled "Important News" -->
<p>To play today's games you will need to update your client.</p>
<h2>Games</h2> <!-- this starts a third subsection -->
</header>
<p>You have three active games:</p>
<!-- this is still part of the subsection entitled "Games" -->
...
The footer element represents a footer for its nearest ancestor
sectioning content or sectioning root element. A footer typically
contains information about its section such as who wrote it, links to related documents, copyright
data, and the like.
When the footer element contains entire sections, they represent appendices, indexes, long colophons, verbose license
agreements, and other such content.
Contact information for the author or editor of a section belongs in an
address element, possibly itself inside a footer. Bylines and other
information that could be suitable for both a header or a footer can be
placed in either (or neither). The primary purpose of these elements is merely to help the author
write self-explanatory markup that is easy to maintain and style; they are not intended to impose
specific structures on authors.
Footers don't necessarily have to appear at the end of a section, though they usually
do.
Here is a page with two footers, one at the top and one at the bottom, with the same
content:
<body>
<footer><a href="../">Back to index...</a></footer>
<hgroup>
<h1>Lorem ipsum</h1>
<h2>The ipsum of all lorems</h2>
</hgroup>
<p>A dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
ea commodo consequat. Duis aute irure dolor in reprehenderit in
voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.</p>
<footer><a href="../">Back to index...</a></footer>
</body>
Here is an example which shows the footer element being used both for a site-wide
footer and for a section footer.
Some site designs have what is sometimes referred to as "fat footers" — footers that
contain a lot of material, including images, links to other articles, links to pages for sending
feedback, special offers... in some ways, a whole "front page" in the footer.
This fragment shows the bottom of a page on a site with a "fat footer":
The address element represents the contact information for its
nearest article or body element ancestor. If that is the body
element, then the contact information applies to the document as a whole.
For example, a page at the W3C Web site related to HTML might
include the following contact information:
<ADDRESS>
<A href="../People/Raggett/">Dave Raggett</A>,
<A href="../People/Arnaud/">Arnaud Le Hors</A>,
contact persons for the <A href="Activity">W3C HTML Activity</A>
</ADDRESS>
The address element must not be used to represent arbitrary addresses (e.g. postal
addresses), unless those addresses are in fact the relevant contact information. (The
p element is the appropriate element for marking up postal addresses in general.)
The address element must not contain information other than contact
information.
For example, the following is non-conforming use of the
address element:
The contact information consists of all the address elements that have node as an ancestor and do not have another body or
article element ancestor that is a descendant of node.
If node has an ancestor element that is an article element
If node has an ancestor element that is a body element
The contact information of node is the same as the contact information of
the nearest article or body element ancestor, whichever is
nearest.
The contact information of node is the same as the contact information of
the body element of the Document.
Otherwise
There is no contact information for node.
User agents may expose the contact information of a node to the user, or use it for other
purposes, such as indexing sections based on the sections' contact information.
In this example the footer contains contact information and a copyright notice.
The h1–h6 elements and the hgroup element are
headings.
The first element of heading content in an element of sectioning
contentrepresents the heading for that section. Subsequent headings of equal
or higher rank start new (implied) sections, headings of lower rank
start implied subsections that are part of the previous one. In both cases, the element
represents the heading of the implied section.
Certain elements are said to be sectioning roots, including
blockquote and td elements. These elements can have their own outlines,
but the sections and headings inside these elements do not contribute to the outlines of their
ancestors.
Sectioning content elements are always considered subsections of their nearest
ancestor sectioning root or their nearest ancestor element of sectioning
content, whichever is nearest, regardless of what implied sections other headings may have
created.
Notice how the section ends the earlier implicit section so that a later
paragraph ("Grunt") is back at the top level.
Sections may contain headings of any rank, but authors are strongly encouraged to
either use only h1 elements, or to use elements of the appropriate rank
for the section's nesting level.
Authors are also encouraged to explicitly wrap sections in elements of sectioning
content, instead of relying on the implicit sections generated by having multiple headings
in one element of sectioning content.
For example, the following is correct:
<body>
<h4>Apples</h4>
<p>Apples are fruit.</p>
<section>
<h2>Taste</h2>
<p>They taste lovely.</p>
<h6>Sweet</h6>
<p>Red apples are sweeter than green ones.</p>
<h1>Color</h1>
<p>Apples come in various colors.</p>
</section>
</body>
However, the same document would be more clearly expressed as:
<body>
<h1>Apples</h1>
<p>Apples are fruit.</p>
<section>
<h2>Taste</h2>
<p>They taste lovely.</p>
<section>
<h3>Sweet</h3>
<p>Red apples are sweeter than green ones.</p>
</section>
</section>
<section>
<h2>Color</h2>
<p>Apples come in various colors.</p>
</section>
</body>
Both of the documents above are semantically identical and would produce the same outline in
compliant user agents.
This third example is also semantically identical, and might be easier to maintain (e.g. if
sections are often moved around in editing):
<body>
<h1>Apples</h1>
<p>Apples are fruit.</p>
<section>
<h1>Taste</h1>
<p>They taste lovely.</p>
<section>
<h1>Sweet</h1>
<p>Red apples are sweeter than green ones.</p>
</section>
</section>
<section>
<h1>Color</h1>
<p>Apples come in various colors.</p>
</section>
</body>
This final example would need explicit style rules to be rendered well in legacy browsers.
Legacy browsers without CSS support would render all the headings as top-level headings.
4.3.11.1 Creating an outline
This section defines an algorithm for creating an outline for a sectioning content
element or a sectioning root element. It is defined in terms of a walk over the nodes
of a DOM tree, in tree order, with each node being visited when it is entered and when it
is exited during the walk.
The outline for a sectioning content element or a sectioning
root element consists of a list of one or more potentially nested sections. The element for which an outline is created
is said to be the outline's owner.
A section is a container that corresponds to some nodes in
the original DOM tree. Each section can have one heading associated with it, and can contain any
number of further nested sections. The algorithm for the outline also
associates each node in the DOM tree with a particular section and potentially a heading.
(The sections in the outline aren't section elements, though some may correspond to
such elements — they are merely conceptual sections.)
The following markup fragment:
<body>
<hgroup id="document-title">
<h1>HTML</h1>
<h2>Living Standard — Last Updated 12 August 2016</h2>
</hgroup>
<p>Some intro to the document.</p>
<h2>Table of contents</h2>
<ol id=toc>...</ol>
<h2>First section</h2>
<p>Some intro to the first section.</p>
</body>
...results in the following outline being created for the body node (and thus the
entire document):
Associated with heading <hgroup
id="document-title">...</hgroup> consisting of primary heading <h1>HTML</h1> and secondary heading <h2>Living
Standard — Last Updated 12 August 2016</h2>.
Also associated with the paragraph <p>Some intro to the
document.</p> (though it likely would not be shown in a rendered view of the
outline).
Also associated with the paragraph <p>Some intro to the first
section.</p> (though it likely would not be shown in a rendered view of the
outline).
No nested sections.
The following image shows what a rendered view of the outline might look like.
The algorithm that must be followed during a walk of a DOM subtree rooted at a sectioning
content element or a sectioning root element to determine that element's
outline is as follows:
Let current outline target be null. (It holds the element whose
outline is being created.)
Let current section be null. (It holds a pointer to a section, so that elements in the DOM can all be associated with a
section.)
Create a stack to hold elements, which is used to handle nesting. Initialize this stack to
empty.
Walk over the DOM in tree order, starting with the sectioning
content element or sectioning root element at the root of the subtree for
which an outline is to be created, and trigger the first relevant step below for each element as
the walk enters and exits it.
When exiting an element, if that element is the element at the top of the stack
The element being exited is a heading content element or an
element with a hidden attribute.
Pop that element from the stack.
If the top of the stack is a heading content element or an element with a
hidden attribute
If the current section has no heading, create an implied heading
and let that be the heading for the current section.
Pop the top element from the stack, and let the current outline
target be that element.
Let current section be the last section in the
outline of the current outline target element.
Append the outline of the sectioning content element being
exited to the current section. (This does not change which section is
the last section in the outline.)
The current outline target is the element being exited,
and it is the sectioning content element or a sectioning root
element at the root of the subtree for which an outline is being generated.
If the current section has no heading, create an implied heading and
let that be the heading for the current section.
Skip to the next step in the overall set of steps. (The walk is over.)
If the current section has no heading, let the element being entered be
the heading for the current section.
If the element being entered is an hgroup element, that
hgroup as a whole is a multi-level heading for the current
section, with the highest-rankedh1–h6 descendant of the hgroup providing the
primary heading for the current section, and with other
h1–h6 descendants of the hgroup providing
secondary headings for the current section.
Otherwise, if the element being entered has a rank equal to or higher than the
heading of the last section of the outline of the current outline
target, or if the heading of the last section of the outline of the current outline target is an implied heading, then create a new section and append it to the outline of the current outline target element, so that this new section is the new last
section of that outline. Let current section be that new section. Let the
element being entered be the new heading for the current section.
Otherwise, run these substeps:
Let candidate section be current
section.
Heading loop: If the element being entered has a rank lower than
the rank of the heading of the candidate section, then create a new
section, and append it to candidate
section. (This does not change which section is the last section in the outline.) Let
current section be this new section. Let the element being entered be the
new heading for the current section. Abort these substeps.
Let new candidate section be the section that contains candidate section in
the outline of current outline target.
Let candidate section be new candidate
section.
Return to the step labeled heading loop.
Push the element being entered onto the stack. (This causes the algorithm to skip any
descendants of the element.)
Recall that h1 has the highest rank, and h6
has the lowest rank.
Otherwise
Do nothing.
In addition, whenever the walk exits a node, after doing the steps
above, if the node is not associated with a section yet,
associate the node with the sectioncurrent
section.
Associate all non-element nodes that are in the subtree for which an outline is being
created with the section with which their parent element is
associated.
Associate all nodes in the subtree with the heading of the section with which they are associated, if any.
The tree of sections created by the algorithm above, or a proper subset thereof, must be used
when generating document outlines, for example when generating tables of contents.
When creating an interactive table of contents, entries should jump the user to the relevant
sectioning content element, if the section was
created for a real element in the original document, or to the relevant heading
content element, if the section in the tree was
generated for a heading in the above process.
Selecting the first section of the document
therefore always takes the user to the top of the document, regardless of where the first heading
in the body is to be found.
Although it contains no headings, this snippet has three sections: a document (the
body) with two subsections (a nav and an aside). A user
agent could present the outline as follows:
Untitled document
Navigation
Sidebar
These default headings ("Untitled document", "Navigation", "Sidebar") are not specified by
this specification, and might vary with the user's language, the page's language, the user's
preferences, the user agent implementor's preferences, etc.
The following JavaScript function shows how the tree walk could be implemented. The root argument is the root of the tree to walk (either a sectioning
content element or a sectioning root element), and the enter and exit arguments are callbacks that are called with
the nodes as they are entered and exited. [JAVASCRIPT]
function (root, enter, exit) {
var node = root;
start: while (node) {
enter(node);
if (node.firstChild) {
node = node.firstChild;
continue start;
}
while (node) {
exit(node);
if (node == root) {
node = null;
} else if (node.nextSibling) {
node = node.nextSibling;
continue start;
} else {
node = node.parentNode;
}
}
}
}
4.3.11.2 Sample outlines
This section is non-normative.
The following document shows a straight-forward application of the outline
algorithm. First, here is the document, which is a book with very short chapters and
subsections:
<!DOCTYPE HTML>
<html lang=en>
<title>The Tax Book (all in one page)</title>
<h1>The Tax Book</h1>
<h2>Earning money</h2>
<p>Earning money is good.</p>
<h3>Getting a job</h3>
<p>To earn money you typically need a job.</p>
<h2>Spending money</h2>
<p>Spending is what money is mainly used for.</p>
<h3>Cheap things</h3>
<p>Buying cheap things often not cost-effective.</p>
<h3>Expensive things</h3>
<p>The most expensive thing is often not the most cost-effective either.</p>
<h2>Investing money</h2>
<p>You can lend your money to other people.</p>
<h2>Losing money</h2>
<p>If you spend money or invest money, sooner or later you will lose money.
<h3>Poor judgement</h3>
<p>Usually if you lose money it's because you made a mistake.</p>
This book would form the following outline:
The Tax Book
Earning money
Getting a job
Spending money
Cheap things
Expensive things
Investing money
Losing money
Poor judgement
Notice that the title element does not participate in the outline.
Here is a similar document, but this time using section elements to get the same
effect:
<!DOCTYPE HTML>
<html lang=en>
<title>The Tax Book (all in one page)</title>
<h1>The Tax Book</h1>
<section>
<h1>Earning money</h1>
<p>Earning money is good.</p>
<section>
<h1>Getting a job</h1>
<p>To earn money you typically need a job.</p>
</section>
</section>
<section>
<h1>Spending money</h1>
<p>Spending is what money is mainly used for.</p>
<section>
<h1>Cheap things</h1>
<p>Buying cheap things often not cost-effective.</p>
</section>
<section>
<h1>Expensive things</h1>
<p>The most expensive thing is often not the most cost-effective either.</p>
</section>
</section>
<section>
<h1>Investing money</h1>
<p>You can lend your money to other people.</p>
</section>
<section>
<h1>Losing money</h1>
<p>If you spend money or invest money, sooner or later you will lose money.
<section>
<h1>Poor judgement</h1>
<p>Usually if you lose money it's because you made a mistake.</p>
</section>
</section>
This book would form the same outline:
The Tax Book
Earning money
Getting a job
Spending money
Cheap things
Expensive things
Investing money
Losing money
Poor judgement
A document can contain multiple top-level headings:
This result is described as unintuitive because it results in three subsections even
though there's only one section element. Effectively, the section is
split into three, just like the implied body element in the previous example.
(In this example, "(untitled page)" is the implied heading for the body
element, since it has no explicit heading.)
Headings never rise above other sections. Thus, in the following example, the first
h1 does not actually describe the page header; it describes the header for the
second half of the page:
<!DOCTYPE HTML>
<html lang=en>
<title>Feathers on The Site of Encyclopedic Knowledge</title>
<section>
<h1>A plea from our caretakers</h1>
<p>Please, we beg of you, send help! We're stuck in the server room!</p>
</section>
<h1>Feathers</h1>
<p>Epidermal growths.</p>
The resulting outline would be:
(untitled page)
A plea from our caretakers
Feathers
Thus, when an article element starts with a nav block and only later
has its heading, the result is that the nav block is not part of the same section as
the rest of the article in the outline. For instance, take this document:
<!DOCTYPE HTML>
<html lang="en">
<title>We're adopting a child! — Ray's blog</title>
<h1>Ray's blog</h1>
<article>
<header>
<nav>
<a href="?t=-1d">Yesterday</a>;
<a href="?t=-7d">Last week</a>;
<a href="?t=-1m">Last month</a>
</nav>
<h1>We're adopting a child!</h1>
</header>
<main>
<p>As of today, Janine and I have signed the papers to become
the proud parents of baby Diane! We've been looking forward to
this day for weeks.</p>
</main>
</article>
</html>
The resulting outline would be:
Ray's blog
Untitled article
Untitled navigation section
We're adopting a child!
Also worthy of note in this example is that the header and main
elements have no effect whatsoever on the document outline.
The hgroup element can be used for subheadings. For example:
<!DOCTYPE HTML>
<html lang="en">
<title>Chronotype: CS Student</title>
<hgroup>
<h1> The morning </h1>
<h2> 06:00 to 12:00 </h2>
</hgroup>
<p>We sleep.</p>
<hgroup>
<h1> The afternoon </h1>
<h2> 12:00 to 18:00 </h2>
</hgroup>
<p>We study.</p>
<hgroup>
<h2>Additional Commentary</h2>
<h3>Because not all this is necessarily true</h3>
<h6>Ok it's almost certainly not true</h6>
</hgroup>
<p>Yeah we probably play, rather than study.</p>
<hgroup>
<h1> The evening </h1>
<h2> 18:00 to 00:00 </h2>
</hgroup>
<p>We play.</p>
<hgroup>
<h1> The night </h1>
<h2> 00:00 to 06:00 </h2>
</hgroup>
<p>We play some more.</p>
</html>
The resulting outline would be:
The morning 06:00 to 12:00
The afternoon 12:00 to 18:00
Additional Commentary Because not all this is necessarily true Ok it's almost certainly not true
The evening 18:00 to 00:00
The night 00:00 to 06:00
Exactly how this is represented by user agents, as most interface issues, is left as a matter
of implementation preference, but the key part is that the hgroup's descendant
h1–h6 elements are what form the element's heading. Thus, the
following would be equally valid:
The morning — 06:00 to 12:00
The afternoon — 12:00 to 18:00
Additional Commentary — Because not all this is necessarily true — Ok it's almost certainly not true
The evening — 18:00 to 00:00
The night — 00:00 to 06:00
But so would the following:
The morning
The afternoon
Additional Commentary
The evening
The night
The following would also be valid, though maybe less practical in most contexts:
The morning
06:00 to 12:00
The afternoon
12:00 to 18:00
Additional Commentary
Because not all this is necessarily true
Ok it's almost certainly not true
The evening
18:00 to 00:00
The night
00:00 to 06:00
4.3.11.3 Exposing outlines to users
User agents are encouraged to expose page outlines to users to aid in navigation. This is
especially true for non-visual media, e.g. screen readers.
However, to mitigate the difficulties that arise from authors misusing sectioning
content, user agents are also encouraged to offer a mode that navigates the page using
heading content alone.
For instance, a user agent could map the arrow keys as follows:
Shift+← Left
Go to previous section, including subsections of previous sections
Shift+→ Right
Go to next section, including subsections of the current section
Shift+↑ Up
Go to parent section of the current section
Shift+↓ Down
Go to next section, skipping subsections of the current section
Plus in addition, the user agent could map the j and
k keys to navigating to the previous or next element of heading
content, regardless of the section's outline depth and ignoring sections with no
headings.
A complete, or self-contained, composition in a document, page, application, or site and that is, in principle, independently distributable or reusable, e.g. in syndication. This could be a forum post, a magazine or newspaper article, a blog entry, a user-submitted comment, an interactive widget or gadget, or any other independent item of content.
<article>
<img src="/tumblr_masqy2s5yn1rzfqbpo1_500.jpg" alt="Yellow smiley face with the caption 'masif'">
<p>My fave Masif tee so far!</p>
<footer>Posted 2 days ago</footer>
</article><article>
<img src="/tumblr_m9tf6wSr6W1rzfqbpo1_500.jpg" alt="">
<p>Happy 2nd birthday Masif Saturdays!!!</p>
<footer>Posted 3 weeks ago</footer>
</article>
A section of a page that consists of content that is tangentially related to the content around the aside element, and which could be considered separate from that content. Such sections are often represented as sidebars in printed typography.
<h1>Music</h1>
<p>As any burner can tell you, the event has a lot of trance.</p>
<aside>You can buy the music we played at our <a href="buy.html">playlist page</a>.</aside>
<p>This year we played a kind of trance that originated in Belgium, Germany, and the Netherlands in the mid 90s.</p>
<h1>The Guide To Music On The Playa</h1><h2>The Main Stage</h2>
<p>If you want to play on a stage, you should bring one.</p>
<h2>Amplified Music</h2>
<p>Amplifiers up to 300W or 90dB are welcome.</p>
The heading of a section, which consists of all the h1–h6 element children of the hgroup element. The element is used to group a set of h1–h6 elements when the heading has multiple levels, such as subheadings, alternative titles, or taglines.
<hgroup>
<h1>Burning Music</h1>
<h2>The Guide To Music On The Playa</h2>
</hgroup>
<section>
<hgroup>
<h1>Main Stage</h1>
<h2>The Fiction Of A Music Festival</h2>
</hgroup>
<p>If you want to play on a stage, you should bring one.</p>
</section>
<section>
<hgroup>
<h1>Loudness!</h1>
<h2>Questions About Amplified Music</h2>
</hgroup>
<p>Amplifiers up to 300W or 90dB are welcome.</p>
</section>
<article>
<header>
<h1>Hard Trance is My Life</h1>
<p>By DJ Steve Hill and Technikal</p>
</header>
<p>The album with the amusing punctuation has red artwork.</p>
</article>
A footer for its nearest ancestor sectioning content or sectioning root element. A footer typically contains information about its section such as who wrote it, links to related documents, copyright data, and the like.
<article>
<h1>Hard Trance is My Life</h1>
<p>The album with the amusing punctuation has red artwork.</p>
<footer>
<p>Artists: DJ Steve Hill and Technikal</p>
</footer>
</article>
4.3.12.1 Article or section?
This section is non-normative.
A section forms part of something else. An article is its own thing.
But how does one know which is which? Mostly the real answer is "it depends on author intent".
For example, one could imagine a book with a "Granny Smith" chapter that just said "These
juicy, green apples make a great filling for apple pies."; that would be a section
because there'd be lots of other chapters on (maybe) other kinds of apples.
On the other hand, one could imagine a tweet or reddit comment or tumblr post or newspaper
classified ad that just said "Granny Smith. These juicy, green apples make a great filling for
apple pies."; it would then be articles because that was the whole thing.
A comment on an article is not part of the article on which it is commenting,
therefore it is its own article.
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 herself on a piece of
carpet. Later in her 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.
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
fiveparagraphs 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.
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.
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.
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>
Content inside a blockquote must be quoted from another source, whose address, if
it has one, may be cited in the cite
attribute.
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 content of a blockquote may be abbreviated or may have context added in the
conventional manner for the text's language.
For example, in English this is traditionally done using square brackets. Consider a page with
the sentence "Jane ate the cracker. She then said she liked apples and fish."; it could be quoted
as follows:
<blockquote>
<p>[Jane] then said she liked [...] fish.</p>
</blockquote>
Attribution for the quotation, if any, must be placed outside the blockquote
element.
For example, here the attribution is given in a paragraph after the quote:
<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>
</blockquote>
<p>— Stephen Roberts</p>
The other examples below show other ways of showing attribution.
The cite IDL attribute must reflect
the element's cite content attribute.
Here a blockquote element is used in conjunction with a figure
element and its figcaption to clearly relate a quote to its attribution (which is
not part of the quote and therefore doesn't belong inside the blockquote
itself):
<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>Carl Sagan, 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>
<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>
<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...
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, ...).
Support: ol-reversedChrome for Android56+Chrome20+UC Browser for Android11+iOS Safari6.0+Firefox18+IENoneSamsung Internet4+Opera Miniall+Android Browser4.4+Safari6.1+EdgeNoneOpera12.1+
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 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 and
type IDL attributes must reflect the
respective content attributes of the same name.
The start IDL attribute must reflect
the content attribute of the same name, with a default value of 1.
This means that the start IDL attribute does
not necessarily match the list's starting value, in cases
where the start content attribute is omitted and the reversed content attribute is specified.
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>
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>
An li element's end tag can be omitted if the
li element is immediately followed by another li element or if there is
no more content in the parent element.
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.
The value attribute, if present, must be a
valid integer. It is used to determine the ordinal value of the list
item, when the li's list owner is an ol element.
Any element whose computed value of 'display' is 'list-item' has a
list owner, which is determined as follows:
If owner is an ol element, and owner has a reversed attribute, decrement numbering by 1;
otherwise, increment numbering by 1.
Increment i by 1.
Go to the step labeled loop.
The value IDL attribute must reflect
the value of the value content attribute.
The element's value IDL attribute does not directly
correspond to its ordinal value; it simply reflects
the content attribute. For example, given this list:
The ordinal values are 1, 3, and 4, whereas the value IDL attributes return 0, 3, 0 on getting.
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. h1) 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.
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.
The dl element represents an association list consisting of zero or
more name-value groups (a description list). A name-value group consists of one or more names
(dt elements, possibly as children of a div element child) followed by
one or more values (dd elements, possibly as children of a div element
child), ignoring any nodes other than dt and dd element children, and
dt and dd elements that are children of div element
children. Within a single dl element, there should not be more than one
dt element for each name.
Name-value groups may be terms and definitions, metadata topics and values, questions and
answers, or any other groups of name-value data.
The values within a group are alternatives; multiple paragraphs forming part of the same value
must all be given within the same dd element.
The order of the list of groups, and of the names and values within each group, may be
significant.
In order to annotate groups with microdata attributes, or other global
attributes that apply to whole groups, or just for styling purposes, each group in a
dl element can be wrapped in a div element. This does not change the
semantics of the dl element.
The name-value groups of a dl element dl are determined using the
following algorithm. A name-value group has a name (a list of dt elements, initially
empty) and a value (a list of dd elements, initially empty).
If current is not empty, then append current to
groups.
Return groups.
To process dt or dd for a node node means to
follow these steps:
Let groups, current, and seenDd be the same variables as
those of the same name in the algorithm that invoked these steps.
If node is a dt element, then follow these substeps:
If seenDd is true, then append current to groups, set
current to a new name-value group, and set seenDd to false.
Append node to current's name.
Otherwise, if node is a dd element, then append node to
current's value and set seenDd to true.
When a name-value group has an empty list as name or value, it is often due to
accidentally using dd elements in the place of dt elements and vice
versa. Conformance checkers can spot such mistakes and might be able to advise authors how to
correctly use the markup.
In the following example, one entry ("Authors") is linked to two values ("John" and
"Luke").
<dl>
<dt> Authors
<dd> John
<dd> Luke
<dt> Editor
<dd> Frank
</dl>
In the following example, one definition is linked to two terms.
<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>
The following example illustrates the use of the dl element to mark up metadata
of sorts. At the end of the example, one group has two metadata labels ("Authors" and "Editors")
and two values ("Robert Rothman" and "Daniel Jackson"). This example also uses the
div element around the groups of dt and dd element, to aid
with styling.
<dl>
<div>
<dt> Last modified time </dt>
<dd> 2004-12-23T23:33Z </dd>
</div>
<div>
<dt> Recommended update interval </dt>
<dd> 60s </dd>
</div>
<div>
<dt> Authors </dt>
<dt> Editors </dt>
<dd> Robert Rothman </dd>
<dd> Daniel Jackson </dd>
</div>
</dl>
The following example shows the dl element used to give a set of instructions.
The order of the instructions here is important (in the other examples, the order of the blocks
was not 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>
The following snippet shows a dl element being used as a glossary. Note the use
of dfn to indicate the word being defined.
<dl>
<dt><dfn>Apartment</dfn>, n.</dt>
<dd>An execution context grouping one or more threads with one or
more COM objects.</dd>
<dt><dfn>Flat</dfn>, n.</dt>
<dd>A deflated tire.</dd>
<dt><dfn>Home</dfn>, n.</dt>
<dd>The user's login directory.</dd>
</dl>
This example uses microdata attributes in a dl element, together
with the div element, to annotate the ice cream desserts at a French restaurant.
The dt element represents the term, or name, part of a
term-description group in a description list (dl element).
The dt element itself, when used in a dl element, does
not indicate that its contents are a term being defined, but this can be indicated using the
dfn element.
This example shows a list of frequently asked questions (a FAQ) marked up using the
dt element for questions and the dd element for answers.
<article>
<h1>FAQ</h1>
<dl>
<dt>What do we want?</dt>
<dd>Our data.</dd>
<dt>When do we want it?</dt>
<dd>Now.</dd>
<dt>Where is it?</dt>
<dd>We are not sure.</dd>
</dl>
</article>
A dd element's end tag can 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.
The dd element represents the description, definition, or value, part
of a term-description group in a description list (dl element).
A dl can be used to define a vocabulary list, like in a dictionary. In the
following example, each entry, given by a dt with a dfn, has several
dds, showing the various parts of the definition.
<dl>
<dt><dfn>happiness</dfn></dt>
<dd class="pronunciation">/'hæ p. nes/</dd>
<dd class="part-of-speech"><i><abbr>n.</abbr></i></dd>
<dd>The state of being happy.</dd>
<dd>Good fortune; success. <q>Oh <b>happiness</b>! It worked!</q></dd>
<dt><dfn>rejoice</dfn></dt>
<dd class="pronunciation">/ri jois'/</dd>
<dd><i class="part-of-speech"><abbr>v.intr.</abbr></i> To be delighted oneself.</dd>
<dd><i class="part-of-speech"><abbr>v.tr.</abbr></i> To cause one to be delighted.</dd>
</dl>
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 first figcaption element child of the element, 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<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>
<html lang="en">
<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.
<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 previous example could also be more succinctly written as follows (using title attributes in place of the nested
figure/figcaption pairs):
<figure>
<img src="castle1423.jpeg" title="Etching. Anonymous, ca. 1423."
alt="The castle has one tower, and a tall wall around it.">
<img src="castle1858.jpeg" title="Oil-based paint on canvas. Maria Towle, 1858."
alt="The castle now has two towers and two walls.">
<img src="castle1999.jpeg" title="Film photograph. Peter Jankle, 1999."
alt="The castle lies in ruins, the original tower all that remains in one piece.">
<figcaption>The castle through the ages: 1423, 1858, and 1999 respectively.</figcaption>
</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>
The main element can be used as a container for the dominant contents of another
element. It represents its children.
The main element is distinct from the section and
article elements in that the main element does not contribute to the
document outline.
There is no restriction as to the number of main elements in a
document. Indeed, there are many cases where it would make sense to have multiple
main elements. For example, a page with multiple article elements might
need to indicate the dominant contents of each such element.
In this example, the author has used a presentation where each component of the page is
rendered in a box. To wrap the main content of the page (as opposed to the header, the footer,
the navigation bar, and a sidebar), the main element is used.
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.
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. It can also be used in a dl
element, wrapping groups of dt and dd 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">
<h1>My use of language and my cats</h1>
<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, coloured 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 recognises 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 "colour"...</p>
</div>
<p>I should say "sidewalk" and "apartment" and "color"!</p>
</article>
If the a element has an href attribute,
then it represents a hyperlink (a hypertext anchor) labeled by its
contents.
If the a element has no href attribute,
then the element represents a placeholder for where a link might otherwise have been
placed, if it had been relevant, consisting of just the element's contents.
If the itemprop attribute is specified on an a element,
then the href attribute must also be specified.
If a site uses a consistent navigation toolbar on every page, then the link that would
normally link to the page itself could be marked up using an a element:
Abort these steps without following the hyperlink.
If the target of the click event is an img
element with an ismap attribute specified, then server-side
image map processing must be performed, as follows:
Let x and y be zero.
If the click event was a real pointing-device-triggered
click event on the img element, then set
x to the distance in CSS pixels from the left edge of the
image to the location of the click, and set y to the distance in CSS pixels from the top edge of the image to the location of the
click.
If x is negative, set x to zero.
If y is negative, set y to zero.
Let hyperlink suffix be a U+003F QUESTION MARK character, the value of
x expressed as a base-ten integer using ASCII digits, a U+002C COMMA
character (,), and the value of y expressed as a base-ten integer using ASCII
digits.
Finally, the user agent must follow the
hyperlink or download the hyperlink created
by the a element, as determined by the download attribute and any expressed user preference,
passing hyperlink suffix, if the steps above defined it.
The text IDL attribute, on getting, must return the
same value as the textContent IDL attribute on the element, and on setting, must act
as if the textContent IDL attribute on the element had been set to the new value.
The a element may be wrapped around entire paragraphs, lists, tables, and so
forth, even entire sections, so long as there is no interactive content within (e.g. buttons or
other links). This example shows how this can be used to make an entire advertising block into a
link:
<aside class="advertising">
<h1>Advertising</h1>
<a href="https://ad.example.com/?adid=1929&pubid=1422">
<section>
<h1>Mellblomatic 9000!</h1>
<p>Turn all your widgets into mellbloms!</p>
<p>Only $9.99 plus shipping and handling.</p>
</section>
</a>
<a href="https://ad.example.com/?adid=375&pubid=1422">
<section>
<h1>The Mellblom Browser</h1>
<p>Web browsing at the speed of light.</p>
<p>No other browser goes faster!</p>
</section>
</a>
</aside>
The em element represents stress emphasis of its contents.
The level of stress that a particular piece of content has is given by its number of ancestor
em elements.
The placement of stress emphasis changes the meaning of the sentence. The element thus forms an
integral part of the content. The precise way in which stress is used in this way depends on the
language.
These examples show how changing the stress emphasis changes the meaning. First, a general
statement of fact, with no stress:
<p>Cats are cute animals.</p>
By emphasizing the first word, the statement implies that the kind of animal under discussion
is in question (maybe someone is asserting that dogs are cute):
<p><em>Cats</em> are cute animals.</p>
Moving the stress to the verb, one highlights that the truth of the entire sentence is in
question (maybe someone is saying cats are not cute):
<p>Cats <em>are</em> cute animals.</p>
By moving it to the adjective, the exact nature of the cats is reasserted (maybe someone
suggested cats were mean animals):
<p>Cats are <em>cute</em> animals.</p>
Similarly, if someone asserted that cats were vegetables, someone correcting this might
emphasize the last word:
<p>Cats are cute <em>animals</em>.</p>
By emphasizing the entire sentence, it becomes clear that the speaker is fighting hard to get
the point across. This kind of stress emphasis also typically affects the punctuation, hence the
exclamation mark here.
<p><em>Cats are cute animals!</em></p>
Anger mixed with emphasizing the cuteness could lead to markup such as:
<p><em>Cats are <em>cute</em> animals!</em></p>
The em element isn't a generic "italics" element. Sometimes, text is intended to
stand out from the rest of the paragraph, as if it was in a different mood or voice. For this,
the i element is more appropriate.
The em element also isn't intended to convey importance; for that purpose, the
strong element is more appropriate.
The strong element represents strong importance, seriousness, or
urgency for its contents.
Importance: the strong element can be used in a heading, caption,
or paragraph to distinguish the part that really matters from other parts that might be more
detailed, more jovial, or merely boilerplate. (This is distinct from marking up subheadings, for
which the hgroup element is appropriate.)
For example, the first word of the previous paragraph is marked up with
strong to distinguish it from the more detailed text in the rest of the
paragraph.
Seriousness: the strong element can be used to mark up a warning
or caution notice.
Urgency: the strong element can be used to denote contents that
the user needs to see sooner than other parts of the document.
The relative level of importance of a piece of content is given by its number of ancestor
strong elements; each strong element increases the importance of its
contents.
Changing the importance of a piece of text with the strong element does not change
the meaning of the sentence.
Here, the word "chapter" and the actual chapter number are mere boilerplate, and the actual
name of the chapter is marked up with strong:
<h1>Chapter 1: <strong>The Praxis</strong></h1>
In the following example, the name of the diagram in the caption is marked up with
strong, to distinguish it from boilerplate text (before) and the description
(after):
<figcaption>Figure 1. <strong>Ant colony dynamics</strong>. The ants in this colony are
affected by the heat source (upper left) and the food source (lower right).</figcaption>
In this example, the heading is really "Flowers, Bees, and Honey", but the author has added a
light-hearted addition to the heading. The strong element is thus used to mark up
the first part to distinguish it from the latter part.
<h1><strong>Flowers, Bees, and Honey</strong> and other things I don't understand</h1>
Here is an example of a warning notice in a game, with the
various parts marked up according to how important they are:
<p><strong>Warning.</strong> This dungeon is dangerous.
<strong>Avoid the ducks.</strong> Take any gold you find.
<strong><strong>Do not take any of the diamonds</strong>,
they are explosive and <strong>will destroy anything within
ten meters.</strong></strong> You have been warned.</p>
In this example, the strong element is used to denote the part of the text that
the user is intended to read first.
<p>Welcome to Remy, the reminder system.</p>
<p>Your tasks for today:</p>
<ul>
<li><p><strong>Turn off the oven.</strong></p></li>
<li><p>Put out the trash.</p></li>
<li><p>Do the laundry.</p></li>
</ul>
The small element represents side comments such as small print.
Small print typically features disclaimers, caveats, legal restrictions, or
copyrights. Small print is also sometimes used for attribution, or for satisfying licensing
requirements.
The small element does not "de-emphasize" or lower the importance of
text emphasized by the em element or marked as important with the strong
element. To mark text as not emphasized or important, simply do not mark it up with the
em or strong elements respectively.
The small element should not be used for extended spans of text, such as multiple
paragraphs, lists, or sections of text. It is only intended for short runs of text. The text of a
page listing terms of use, for instance, would not be a suitable candidate for the
small element: in such a case, the text is not a side comment, it is the main content
of the page.
The small element must not be used for subheadings; for that purpose, use the
hgroup element.
In this example, the small element is used to indicate that value-added tax is
not included in a price of a hotel room:
<dl>
<dt>Single room
<dd>199 € <small>breakfast included, VAT not included</small>
<dt>Double room
<dd>239 € <small>breakfast included, VAT not included</small>
</dl>
In this second example, the small element is used for a side comment in an
article.
<p>Example Corp today announced record profits for the
second quarter <small>(Full Disclosure: Foo News is a subsidiary of
Example Corp)</small>, leading to speculation about a third quarter
merger with Demo Group.</p>
This is distinct from a sidebar, which might be multiple paragraphs long and is removed from
the main flow of text. In the following example, we see a sidebar from the same article. This
sidebar also has small print, indicating the source of the information in the sidebar.
<aside>
<h1>Example Corp</h1>
<p>This company mostly creates small software and Web
sites.</p>
<p>The Example Corp company mission is "To provide entertainment
and news on a sample basis".</p>
<p><small>Information obtained from <a
href="https://example.com/about.html">example.com</a> home
page.</small></p>
</aside>
In this last example, the small element is marked as being important
small print.
<p><strong><small>Continued use of this service will result in a kiss.</small></strong></p>
The s element represents contents that are no longer accurate or no
longer relevant.
The s element is not appropriate when indicating document edits; to
mark a span of text as having been removed from a document, use the del element.
In this example a recommended retail price has been marked as no longer relevant as the
product in question has a new sale price.
<p>Buy our Iced Tea and Lemonade!</p>
<p><s>Recommended retail price: $3.99 per bottle</s></p>
<p><strong>Now selling for just $2.99 a bottle!</strong></p>
The cite element represents the title of a work (e.g.
a book,
a paper,
an essay,
a poem,
a score,
a song,
a script,
a film,
a TV show,
a game,
a sculpture,
a painting,
a theatre production,
a play,
an opera,
a musical,
an exhibition,
a legal case report,
a computer program,
etc). This can be a work that is being quoted or referenced in detail (i.e. a citation), or it can
just be a work that is mentioned in passing.
A person's name is not the title of a work — even if people call that person a piece of
work — and the element must therefore not be used to mark up people's names. (In some cases,
the b element might be appropriate for names; e.g. in a gossip article where the
names of famous people are keywords rendered with a different style to draw attention to them. In
other cases, if an element is really needed, the span element can be
used.)
This next example shows a typical use of the cite element:
<p>My favorite book is <cite>The Reality Dysfunction</cite> by
Peter F. Hamilton. My favorite comic is <cite>Pearls Before
Swine</cite> by Stephan Pastis. My favorite track is <cite>Jive
Samba</cite> by the Cannonball Adderley Sextet.</p>
This is correct usage:
<p>According to the Wikipedia article <cite>HTML</cite>, as it
stood in mid-February 2008, leaving attribute values unquoted is
unsafe. This is obviously an over-simplification.</p>
The following, however, is incorrect usage, as the cite element here is
containing far more than the title of the work:
<!-- do not copy this example, it is an example of bad usage! -->
<p>According to <cite>the Wikipedia article on HTML</cite>, as it
stood in mid-February 2008, leaving attribute values unquoted is
unsafe. This is obviously an over-simplification.</p>
The cite element is obviously a key part of any citation in a bibliography, but
it is only used to mark the title:
<p><cite>Universal Declaration of Human Rights</cite>, United Nations,
December 1948. Adopted by General Assembly resolution 217 A (III).</p>
A citation is not a quote (for which the q element
is appropriate).
This is incorrect usage, because cite is not for quotes:
<p><cite>This is wrong!</cite>, said Ian.</p>
This is also incorrect usage, because a person is not a work:
<p><q>This is still wrong!</q>, said <cite>Ian</cite>.</p>
Quotation punctuation (such as quotation marks) that is quoting the contents of the element
must not appear immediately before, after, or inside q elements; they will be
inserted into the rendering by the user agent.
Content inside a q element must be quoted from another source, whose address, if
it has one, may be cited in the cite attribute. The
source may be fictional, as when quoting characters in a novel or screenplay.
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 q element must not be used in place of quotation marks that do not represent
quotes; for example, it is inappropriate to use the q element for marking up
sarcastic statements.
The use of q elements to mark up quotations is entirely optional; using explicit
quotation punctuation without q elements is just as correct.
Here is a simple example of the use of the q element:
<p>The man said <q>Things that are impossible just take
longer</q>. I disagreed with him.</p>
Here is an example with both an explicit citation link in the q element, and an
explicit citation outside:
<p>The W3C page <cite>About W3C</cite> says the W3C's
mission is <q cite="https://www.w3.org/Consortium/">To lead the
World Wide Web to its full potential by developing protocols and
guidelines that ensure long-term growth for the Web</q>. I
disagree with this mission.</p>
In the following example, the quotation itself contains a quotation:
<p>In <cite>Example One</cite>, he writes <q>The man
said <q>Things that are impossible just take longer</q>. I
disagreed with him</q>. Well, I disagree even more!</p>
In the following example, quotation marks are used instead of the q element:
<p>His best argument was ❝I disagree❞, which
I thought was laughable.</p>
In the following example, there is no quote — the quotation marks are used to name a
word. Use of the q element in this case would be inappropriate.
<p>The word "ineffable" could have been used to describe the disaster
resulting from the campaign's mismanagement.</p>
Defining term: if the dfn element has a title attribute, then the exact value of that attribute
is the term being defined. Otherwise, if it contains exactly one element child node and no child
Text nodes, and that child element is an abbr element with a title attribute, then the exact value of that attribute is
the term being defined. Otherwise, it is the exact textContent of the
dfn element that gives the term being defined.
If the title attribute of the dfn element is
present, then it must contain only the term being defined.
The title attribute of ancestor elements does not
affect dfn elements.
An a element that links to a dfn element represents an instance of
the term defined by the dfn element.
In the following fragment, the term "Garage Door Opener" is first defined in the first
paragraph, then used in the second. In both cases, its abbreviation is what is actually
displayed.
<p>The <dfn><abbr title="Garage Door Opener">GDO</abbr></dfn>
is a device that allows off-world teams to open the iris.</p>
<!-- ... later in the document: -->
<p>Teal'c activated his <abbr title="Garage Door Opener">GDO</abbr>
and so Hammond ordered the iris to be opened.</p>
With the addition of an a element, the reference can be made explicit:
<p>The <dfn id=gdo><abbr title="Garage Door Opener">GDO</abbr></dfn>
is a device that allows off-world teams to open the iris.</p>
<!-- ... later in the document: -->
<p>Teal'c activated his <a href=#gdo><abbr title="Garage Door Opener">GDO</abbr></a>
and so Hammond ordered the iris to be opened.</p>
The abbr element represents an abbreviation or acronym, optionally
with its expansion. The title attribute may be
used to provide an expansion of the abbreviation. The attribute, if specified, must contain an
expansion of the abbreviation, and nothing else.
The paragraph below contains an abbreviation marked up with the abbr element.
This paragraph defines the term "Web Hypertext Application
Technology Working Group".
<p>The <dfn id=whatwg><abbr
title="Web Hypertext Application Technology Working Group">WHATWG</abbr></dfn>
is a loose unofficial collaboration of Web browser manufacturers and
interested parties who wish to develop new technologies designed to
allow authors to write and deploy Applications over the World Wide
Web.</p>
An alternative way to write this would be:
<p>The <dfn id=whatwg>Web Hypertext Application Technology
Working Group</dfn> (<abbr
title="Web Hypertext Application Technology Working Group">WHATWG</abbr>)
is a loose unofficial collaboration of Web browser manufacturers and
interested parties who wish to develop new technologies designed to
allow authors to write and deploy Applications over the World Wide
Web.</p>
This paragraph has two abbreviations. Notice how only one is defined; the other, with no
expansion associated with it, does not use the abbr element.
<p>The
<abbr title="Web Hypertext Application Technology Working Group">WHATWG</abbr>
started working on HTML5 in 2004.</p>
This paragraph links an abbreviation to its definition.
<p>The <a href="#whatwg"><abbr
title="Web Hypertext Application Technology Working Group">WHATWG</abbr></a>
community does not have much representation from Asia.</p>
This paragraph marks up an abbreviation without giving an expansion, possibly as a hook to
apply styles for abbreviations (e.g. smallcaps).
<p>Philip` and Dashiva both denied that they were going to
get the issue counts from past revisions of the specification to
backfill the <abbr>WHATWG</abbr> issue graph.</p>
If an abbreviation is pluralized, the expansion's grammatical number (plural vs singular) must
match the grammatical number of the contents of the element.
Here the plural is outside the element, so the expansion is in the singular:
<p>Two <abbr title="Working Group">WG</abbr>s worked on
this specification: the <abbr>WHATWG</abbr> and the
<abbr>HTMLWG</abbr>.</p>
Here the plural is inside the element, so the expansion is in the plural:
<p>Two <abbr title="Working Groups">WGs</abbr> worked on
this specification: the <abbr>WHATWG</abbr> and the
<abbr>HTMLWG</abbr>.</p>
Abbreviations do not have to be marked up using this element. It is expected to be useful in
the following cases:
Abbreviations for which the author wants to give expansions, where using the
abbr element with a title attribute is an
alternative to including the expansion inline (e.g. in parentheses).
Abbreviations that are likely to be unfamiliar to the document's readers, for which authors
are encouraged to either mark up the abbreviation using an abbr element with a title attribute or include the expansion inline in the text the first
time the abbreviation is used.
Abbreviations whose presence needs to be semantically annotated, e.g. so that they can be
identified from a style sheet and given specific styles, for which the abbr element
can be used without a title attribute.
Providing an expansion in a title attribute once
will not necessarily cause other abbr elements in the same document with the same
contents but without a title attribute to behave as if they had
the same expansion. Every abbr element is independent.
The ruby element allows one or more spans of phrasing content to be marked with
ruby annotations. Ruby annotations are short runs of text presented alongside base text, primarily
used in East Asian typography as a guide for pronunciation or to include other annotations. In
Japanese, this form of typography is also known as furigana.
The content model of ruby elements consists of one or more of the following
sequences:
An rp element followed by one or more rt elements, each of which is itself followed by an rp element
The ruby and rt elements can be used for a variety of kinds of
annotations, including in particular (though by no means limited to) those described below. For
more details on Japanese Ruby in particular, and how to render Ruby for Japanese, see
Requirements for Japanese Text Layout. [JLREQ]
At the time of writing, CSS does not yet provide a way to fully control the
rendering of the HTML ruby element. It is hoped that CSS will be extended to support
the styles described below in due course.
Mono-ruby for individual base characters in Japanese
One or more hiragana or katakana characters (the ruby annotation) are placed with each
ideographic character (the base text). This is used to provide readings of kanji characters.
<ruby>B<rt>annotation</ruby>
In this example, notice how each annotation corresponds to a single base character.
This example can also be written as follows, using one ruby element with two
segments of base text and two annotations (one for each) rather than two back-to-back
ruby elements each with one base text segment and annotation (as in the markup
above):
This is similar to the previous case: each ideographic character in the compound word (the
base text) has its reading given in hiragana or katakana characters (the ruby annotation). The
difference is that the base text segments form a compound word rather than being separate from
each other.
<ruby>B<rt>annotation</rt>B<rt>annotation</ruby>
In this example, notice again how each annotation corresponds to a single base character. In this example, each compound word (jukugo) corresponds to a single ruby element.
The rendering here is expected to be that each annotation be placed over (or next to, in vertical text) the corresponding base character, with the annotations not overhanging any of the adjacent characters.
This is semantically identical to the previous case (each individual ideographic character in
the base compound word has its reading given in an annotation in hiragana or katakana
characters), but the rendering is the more complicated Jukugo Ruby rendering.
This is the same example as above for mono-ruby for compound words. The different rendering is expected to be achieved using different styling (e.g. in CSS), and is not shown here.
The annotation describes the meaning of the base text, rather than (or in addition to) the
pronunciation. As such, both the base text and the annotation can be multiple characters long.
<ruby>BASE<rt>annotation</ruby>
Here a compound ideographic word has its corresponding katakana given as an annotation.
<ruby>境界面<rt>インターフェース</ruby>
境界面
Here a compound ideographic word has its translation in English provided as an annotation.
<ruby lang="ja">編集者<rt lang="en">editor</ruby>
編集者
Group ruby for Jukuji readings
A phonetic reading that corresponds to multiple base characters, because a one-to-one mapping
would be difficult. (In English, the words "Colonel" and "Lieutenant" are examples of words
where a direct mapping of pronunciation to individual letters is, in some dialects, rather
unclear.)
In this example, the name of a species of flowers has a phonetic reading provided using group ruby:
<ruby>紫陽花<rt>あじさい</ruby>
紫陽花
Text with both phonetic and semantic annotations (double-sided ruby)
Sometimes, ruby styles described above are combined.
If this results in two annotations covering the same single base segment, then the
annotations can just be placed back to back.
In more complication situations such as following examples, a nested ruby
element is used to give the inner annotations, and then that whole ruby is then
given an annotation at the "outer" level.
Here both a phonetic reading and the meaning are given in ruby annotations. The annotation on the nested ruby element gives a mono-ruby phonetic annotation for each base character, while the annotation in the rt element that is a child of the outer ruby element gives the meaning using hiragana.
Within a ruby element that does not have a ruby element ancestor,
content is segmented and segments are placed into three categories: base text segments, annotation
segments, and ignored segments. Ignored segments do not form part of the document's semantics
(they consist of some inter-element whitespace and rp elements, the
latter of which are used for legacy user agents that do not support ruby at all). Base text
segments can overlap (with a limit of two segments overlapping any one position in the DOM, and
with any segment having an earlier start point than an overlapping segment also having an equal or
later end point, and any segment have a later end point than an overlapping segment also having an
equal or earlier start point). Annotation segments correspond to rt elements. Each annotation
segment can be associated with a base text segment, and each base text segment can have annotation
segments associated with it. (In a conforming document, each base text segment is associated with
at least one annotation segment, and each annotation segment is associated with one base text
segment.) A ruby element represents the union of the segments of base
text it contains, along with the mapping from those base text segments to annotation segments.
Segments are described in terms of DOM ranges; annotation segment ranges always consist of exactly
one element. [DOM]
At any particular time, the segmentation and categorization of content of a ruby
element is the result that would be obtained from running the following algorithm:
Let base text segments be an empty list of base text segments, each
potentially with a list of base text subsegments.
Let annotation segments be an empty list of annotation segments, each
potentially being associated with a base text segment or subsegment.
Let root be the ruby element for which the algorithm is
being run.
If root has a ruby element ancestor, then jump to the
step labeled end.
Let current parent be root.
Let index be 0.
Let start index be null.
Let parent start index be null.
Let current base text be null.
Start mode: If index is equal to or greater than the number of
child nodes in current parent, then jump to the step labeled end
mode.
If the indexth node in current parent is an
rt or rp element, jump to the step labeled annotation
mode.
Set start index to the value of index.
Base mode: If the indexth node in current
parent is a ruby element, and if current parent is the
same element as root, then push a ruby level and then jump to
the step labeled start mode.
If the indexth node in current parent is an
rt or rp element, then set the current base text and then
jump to the step labeled annotation mode.
Increment index by one.
Base mode post-increment: If index is equal to or greater than
the number of child nodes in current parent, then jump to the step labeled
end mode.
Jump back to the step labeled base mode.
Annotation mode: If the indexth node in current
parent is an rt element, then push a ruby annotation and jump to
the step labeled annotation mode increment.
If the indexth node in current parent is an
rp element, jump to the step labeled annotation mode increment.
If the indexth node in current parent is not a
Text node, or is a Text node that is not inter-element
whitespace, then jump to the step labeled base mode.
Annotation mode increment: Let lookahead index be index plus one.
Annotation mode white-space skipper: If lookahead index is
equal to the number of child nodes in current parent then jump to the step
labeled end mode.
If the lookahead indexth node in current parent is
an rt element or an rp element, then set index to
lookahead index and jump to the step labeled annotation mode.
If the lookahead indexth node in current parent is
not a Text node, or is a Text node that is not inter-element
whitespace, then jump to the step labeled base mode (without further incrementing
index, so the inter-element whitespace seen so far becomes part
of the next base text segment).
Increment lookahead index by one.
Jump to the step labeled annotation mode white-space skipper.
End mode: If current parent is not the same element as root, then pop a ruby level and jump to the step labeled base mode
post-increment.
End: Return base text segments and annotation
segments. Any content of the ruby element not described by segments in either
of those lists is implicitly in an ignored segment.
When the steps above say to set the current base text, it means to run the following
steps at that point in the algorithm:
Let text range be a DOM range whose start is the boundary
point (current parent, start index) and whose
end is the boundary
point (current parent, index).
Let new text segment be a base text segment described by the range
annotation range.
Add new text segment to base text
segments.
Let current base text be new text
segment.
Let start index be null.
When the steps above say to push a ruby level, it means to run the following steps
at that point in the algorithm:
Let current parent be the indexth node in current parent.
Let index be 0.
Set saved start index to the value of start
index.
Let start index be null.
When the steps above say to pop a ruby level, it means to run the following steps at
that point in the algorithm:
Let index be the position of current parent in
root.
Let current parent be root.
Increment index by one.
Set start index to the value of saved start
index.
Let saved start index be null.
When the steps above say to push a ruby annotation, it means to run the following
steps at that point in the algorithm:
Let rt be the rt element that is the indexth node of current parent.
Let annotation range be a DOM range whose start is the boundary
point (current parent, index) and whose end is the boundary point
(current parent, index plus one) (i.e. that contains only
rt).
Let new annotation segment be an annotation segment described by the
range annotation range.
If current base text is not null, associate new
annotation segment with current base text.
Add new annotation segment to annotation
segments.
In this example, each ideograph in the Japanese text 漢字 is annotated with its reading in hiragana.
...
<ruby>漢<rt>かん</rt>字<rt>じ</rt></ruby>
...
This might be rendered as:
In this example, each ideograph in the traditional Chinese text 漢字 is annotated with its bopomofo reading.
<ruby>漢<rt>ㄏㄢˋ</rt>字<rt>ㄗˋ</rt></ruby>
This might be rendered as:
In this example, each ideograph in the simplified Chinese text 汉字 is annotated with its pinyin reading.
...<ruby>汉<rt>hàn</rt>字<rt>zì</rt></ruby>...
This might be rendered as:
In this more contrived example, the acronym "HTML" has four annotations: one for the whole
acronym, briefly describing what it is, one for the letters "HT" expanding them to "Hypertext",
one for the letter "M" expanding it to "Markup", and one for the letter "L" expanding it to
"Language".
<ruby>
<ruby>HT<rt>Hypertext</rt>M<rt>Markup</rt>L<rt>Language</rt></ruby>
<rt>An abstract language for describing documents and applications
</ruby>
An rt element's end tag can be omitted if the
rt element is immediately followed by an rt or rp element,
or if there is no more content in the parent element.
The rt element marks the ruby text component of a ruby annotation. When it is the
child of a ruby element, it doesn't represent
anything itself, but the ruby element uses it as part of determining what itrepresents.
An rt element that is not a child of a ruby element
represents the same thing as its children.
An rp element's end tag can be omitted if the
rp element is immediately followed by an rt or rp element,
or if there is no more content in the parent element.
The rp element can be used to provide parentheses or other content around a ruby
text component of a ruby annotation, to be shown by user agents that don't support ruby
annotations.
An rp element that is a child of a ruby
element represents nothing. An rp element
whose parent element is not a ruby element represents its
children.
The example above, in which each ideograph in the text 漢字 is annotated with its phonetic reading, could be expanded to
use rp so that in legacy user agents the readings are in parentheses:
In conforming user agents the rendering would be as above, but in user agents that do not
support ruby, the rendering would be:
... 漢（かん）字（じ）...
When there are multiple annotations for a segment, rp elements can also be placed
between the annotations. Here is another copy of an earlier contrived example showing some
symbols with names given in English and French, but this time with rp elements as
well:
The data element represents its contents, along with a
machine-readable form of those contents in the value
attribute.
The value attribute must be present. Its value
must be a representation of the element's contents in a machine-readable format.
When the value is date- or time-related, the more specific time
element can be used instead.
The element can be used for several purposes.
When combined with microformats or the microdata attributes defined in
this specification, the element serves to provide both a machine-readable value for the purposes
of data processors, and a human-readable value for the purposes of rendering in a Web browser. In
this case, the format to be used in the value attribute is
determined by the microformats or microdata vocabulary in use.
The element can also, however, be used in conjunction with scripts in the page, for when a
script has a literal value to store alongside a human-readable value. In such cases, the format to
be used depends only on the needs of the script. (The data-*
attributes can also be useful in such situations.)
The value IDL attribute must
reflect the content attribute of the same name.
Here, a short table has its numeric values encoded using the data element so
that the table sorting JavaScript library can provide a sorting mechanism on each column
despite the numbers being presented in textual form in one column and in a decomposed form in
another.
The time element represents its contents, along with a
machine-readable form of those contents in the datetime
attribute. The kind of content is limited to various kinds of dates, times, time-zone offsets, and
durations, as described below.
The datetime attribute may be present. If
present, its value must be a representation of the element's contents in a machine-readable
format.
A time element that does not have a datetime content attribute must not have any element
descendants.
The datetime value of a time element is the value of the element's
datetime content attribute, if it has one, otherwise the
child text content of the time element.
The datetime value of a time element must match one of the following
syntaxes.
Times with dates but without a time zone offset are useful for specifying events
that are observed at the same specific time in each time zone, throughout a day. For example,
the 2020 new year is celebrated at 2020-01-01 00:00 in each time zone, not at the same precise
moment across all time zones. For events that occur at the same time across all time zones, for
example a videoconference meeting, a valid global date and time string is likely
more useful.
For times without dates (or times referring to events that recur on multiple
dates), specifying the geographic location that controls the time is usually more useful than
specifying a time zone offset, because geographic locations change time zone offsets with
daylight savings time. In some cases, geographic locations even change time zone, e.g. when the
boundaries of those time zones are redrawn, as happened with Samoa at the end of 2011. There
exists a time zone database that describes the boundaries of time zones and what rules apply
within each such zone, known as the time zone database. [TZDATABASE]
Times with dates and a time zone offset are useful for specifying specific
events, or recurring virtual events where the time is not anchored to a specific geographic
location. For example, the precise time of an asteroid impact, or a particular meeting in a
series of meetings held at 1400 UTC every day, regardless of whether any particular part of the
world is observing daylight savings time or not. For events where the precise time varies by the
local time zone offset of a specific geographic location, a valid local date and time
string combined with that geographic location is likely more useful.
If the element's datetime value consists of only ASCII digits,
at least one of which is not U+0030 DIGIT ZERO (0), then the machine-readable equivalent is the
base-ten interpretation of those digits, representing a year; abort these steps.
The algorithms referenced above are intended to be designed such that for any
arbitrary string s, only one of the algorithms returns a value. A more
efficient approach might be to create a single algorithm that parses all these data types in one
pass; developing such an algorithm is left as an exercise to the reader.
The dateTime IDL attribute must
reflect the element's datetime content
attribute.
The time element can be used to encode dates, for example in microformats. The
following shows a hypothetical way of encoding an event using a variant on hCalendar that uses
the time element:
<div class="vevent">
<a class="url" href="http://www.web2con.com/">http://www.web2con.com/</a>
<span class="summary">Web 2.0 Conference</span>:
<time class="dtstart" datetime="2005-10-05">October 5</time> -
<time class="dtend" datetime="2005-10-07">7</time>,
at the <span class="location">Argent Hotel, San Francisco, CA</span>
</div>
Here, a fictional microdata vocabulary based on the Atom vocabulary is used with the
time element to mark up a blog post's publication date.
<article itemscope itemtype="https://n.example.org/rfc4287">
<h1 itemprop="title">Big tasks</h1>
<footer>Published <time itemprop="published" datetime="2009-08-29">two days ago</time>.</footer>
<p itemprop="content">Today, I went out and bought a bike for my kid.</p>
</article>
In this example, another article's publication date is marked up using time, this
time using the schema.org microdata vocabulary:
<article itemscope itemtype="http://schema.org/BlogPosting">
<h1 itemprop="headline">Small tasks</h1>
<footer>Published <time itemprop="datePublished" datetime="2009-08-30">yesterday</time>.</footer>
<p itemprop="articleBody">I put a bike bell on her bike.</p>
</article>
In the following snippet, the time element is used to encode a date in the
ISO8601 format, for later processing by a script:
<p>Our first date was <time datetime="2006-09-23">a Saturday</time>.</p>
In this second snippet, the value includes a time:
<p>We stopped talking at <time datetime="2006-09-24T05:00-07:00">5am the next morning</time>.</p>
A script loaded by the page (and thus privy to the page's internal convention of marking up
dates and times using the time element) could scan through the page and look at all
the time elements therein to create an index of dates and times.
For example, this element conveys the string "Friday" with the additional semantic that the
18th of November 2011 is the meaning that corresponds to "Friday":
Today is <time datetime="2011-11-18">Friday</time>.
In this example, a specific time in the Pacific Standard Time timezone is specified:
Your next meeting is at <time datetime="2011-11-18T15:00-08:00">3pm</time>.
The code element represents a fragment of computer code. This could
be an XML element name, a file name, a computer program, or any other string that a computer would
recognize.
There is no formal way to indicate the language of computer code being marked up. Authors who
wish to mark code elements with the language used, e.g. so that syntax highlighting
scripts can use the right rules, can use the class attribute, e.g.
by adding a class prefixed with "language-" to the element.
The following example shows how the element can be used in a paragraph to mark up element
names and computer code, including punctuation.
<p>The <code>code</code> element represents a fragment of computer
code.</p>
<p>When you call the <code>activate()</code> method on the
<code>robotSnowman</code> object, the eyes glow.</p>
<p>The example below uses the <code>begin</code> keyword to indicate
the start of a statement block. It is paired with an <code>end</code>
keyword, which is followed by the <code>.</code> punctuation character
(full stop) to indicate the end of the program.</p>
The following example shows how a block of code could be marked up using the pre
and code elements.
<pre><code class="language-pascal">var i: Integer;
begin
i := 1;
end.</code></pre>
A class is used in that example to indicate the language used.
The var element represents a variable. This could be an actual
variable in a mathematical expression or programming context, an identifier representing a
constant, a symbol identifying a physical quantity, a function parameter, or just be a term used
as a placeholder in prose.
In the paragraph below, the letter "n" is being used as a
variable in prose:
<p>If there are <var>n</var> pipes leading to the ice
cream factory then I expect at <em>least</em> <var>n</var>
flavors of ice cream to be available for purchase!</p>
For mathematics, in particular for anything beyond the simplest of expressions, MathML is more
appropriate. However, the var element can still be used to refer to specific
variables that are then mentioned in MathML expressions.
In this example, an equation is shown, with a legend that references the variables in the
equation. The expression itself is marked up with MathML, but the variables are mentioned in the
figure's legend using var.
<figure>
<math>
<mi>a</mi>
<mo>=</mo>
<msqrt>
<msup><mi>b</mi><mn>2</mn></msup>
<mi>+</mi>
<msup><mi>c</mi><mn>2</mn></msup>
</msqrt>
</math>
<figcaption>
Using Pythagoras' theorem to solve for the hypotenuse <var>a</var> of
a triangle with sides <var>b</var> and <var>c</var>
</figcaption>
</figure>
Here, the equation describing mass-energy equivalence is used in a sentence, and the
var element is used to mark the variables and constants in that equation:
<p>Then she turned to the blackboard and picked up the chalk. After a few moment's
thought, she wrote <var>E</var> = <var>m</var> <var>c</var><sup>2</sup>. The teacher
looked pleased.</p>
This element can be contrasted with the output element, which can be
used to provide immediate output in a Web application.
This example shows the samp element being used
inline:
<p>The computer said <samp>Too much cheese in tray
two</samp> but I didn't know what that meant.</p>
This second example shows a block of sample output from a console program. Nested
samp and kbd elements allow for the styling of specific elements
of the sample output using a style sheet. There's also a few parts of the samp that
are annotated with even more detailed markup, to enable very precise styling. To achieve this,
span elements are used.
<pre><samp><span class="prompt">jdoe@mowmow:~$</span> <kbd>ssh demo.example.com</kbd>
Last login: Tue Apr 12 09:10:17 2005 from mowmow.example.com on pts/1
Linux demo 2.6.10-grsec+gg3+e+fhs6b+nfs+gr0501+++p3+c4a+gr2b-reslog-v6.189 #1 SMP Tue Feb 1 11:22:36 PST 2005 i686 unknown
<span class="prompt">jdoe@demo:~$</span> <span class="cursor">_</span></samp></pre>
This third example shows a block of input and its respective output. The example uses
both code and samp elements.
The kbd element represents user input (typically keyboard input,
although it may also be used to represent other input, such as voice commands).
When the kbd element is nested inside a samp element, it represents
the input as it was echoed by the system.
When the kbd element contains a samp element, it represents
input based on system output, for example invoking a menu item.
When the kbd element is nested inside another kbd element, it
represents an actual key or other single unit of input as appropriate for the input mechanism.
Here the kbd element is used to indicate keys to press:
<p>To make George eat an apple, press <kbd><kbd>Shift</kbd>+<kbd>F3</kbd></kbd></p>
In this second example, the user is told to pick a particular menu item. The outer
kbd element marks up a block of input, with the inner kbd elements
representing each individual step of the input, and the samp elements inside them
indicating that the steps are input based on something being displayed by the system, in this
case menu labels:
<p>To make George eat an apple, select
<kbd><kbd><samp>File</samp></kbd>|<kbd><samp>Eat Apple...</samp></kbd></kbd>
</p>
Such precision isn't necessary; the following is equally fine:
<p>To make George eat an apple, select <kbd>File | Eat Apple...</kbd></p>
These elements must be used only to mark up typographical conventions with specific meanings,
not for typographical presentation for presentation's sake. For example, it would be inappropriate
for the sub and sup elements to be used in the name of the LaTeX
document preparation system. In general, authors should use these elements only if the
absence of those elements would change the meaning of the content.
In certain languages, superscripts are part of the typographical conventions for some
abbreviations.
<p>The most beautiful women are
<span lang="fr"><abbr>M<sup>lle</sup></abbr> Gwendoline</span> and
<span lang="fr"><abbr>M<sup>me</sup></abbr> Denise</span>.</p>
The sub element can be used inside a var element, for variables that
have subscripts.
Here, the sub element is used to represent the subscript that identifies the
variable in a family of variables:
<p>The coordinate of the <var>i</var>th point is
(<var>x<sub><var>i</var></sub></var>, <var>y<sub><var>i</var></sub></var>).
For example, the 10th point has coordinate
(<var>x<sub>10</sub></var>, <var>y<sub>10</sub></var>).</p>
Mathematical expressions often use subscripts and superscripts. Authors are encouraged to use
MathML for marking up mathematics, but authors may opt to use sub and
sup if detailed mathematical markup is not desired. [MATHML]
The i element represents a span of text in an alternate voice or
mood, or otherwise offset from the normal prose in a manner indicating a different quality of
text, such as a taxonomic designation, a technical term, an idiomatic phrase from another
language, transliteration, a thought, or a ship name in Western texts.
<p>The <i class="taxonomy">Felis silvestris catus</i> is cute.</p>
<p>The term <i>prose content</i> is defined above.</p>
<p>There is a certain <i lang="fr">je ne sais quoi</i> in the air.</p>
In the following example, a dream sequence is marked up using
i elements.
<p>Raymond tried to sleep.</p>
<p><i>The ship sailed away on Thursday</i>, he
dreamt. <i>The ship had many people aboard, including a beautiful
princess called Carey. He watched her, day-in, day-out, hoping she
would notice him, but she never did.</i></p>
<p><i>Finally one night he picked up the courage to speak with
her—</i></p>
<p>Raymond woke with a start as the fire alarm rang out.</p>
Authors can use the class attribute on the i
element to identify why the element is being used, so that if the style of a particular use (e.g.
dream sequences as opposed to taxonomic terms) is to be changed at a later date, the author
doesn't have to go through the entire document (or series of related documents) annotating each
use.
Authors are encouraged to consider whether other elements might be more applicable than the
i element, for instance the em element for marking up stress emphasis,
or the dfn element to mark up the defining instance of a term.
Style sheets can be used to format i elements, just like any other
element can be restyled. Thus, it is not the case that content in i elements will
necessarily be italicized.
The b element represents a span of text to which attention is being
drawn for utilitarian purposes without conveying any extra importance and with no implication of
an alternate voice or mood, such as key words in a document abstract, product names in a review,
actionable words in interactive text-driven software, or an article lede.
The following example shows a use of the b element to highlight key words without
marking them up as important:
<p>The <b>frobonitor</b> and <b>barbinator</b> components are fried.</p>
In the following example, objects in a text adventure are highlighted as being special by use
of the b element.
<p>You enter a small room. Your <b>sword</b> glows
brighter. A <b>rat</b> scurries past the corner wall.</p>
<article>
<h2>Kittens 'adopted' by pet rabbit</h2>
<p><b class="lede">Six abandoned kittens have found an
unexpected new mother figure — a pet rabbit.</b></p>
<p>Veterinary nurse Melanie Humble took the three-week-old
kittens to her Aberdeen home.</p>
[...]
As with the i element, authors can use the class
attribute on the b element to identify why the element is being used, so that if the
style of a particular use is to be changed at a later date, the author doesn't have to go through
annotating each use.
The b element should be used as a last resort when no other element is more
appropriate. In particular, headings should use the h1 to h6 elements,
stress emphasis should use the em element, importance should be denoted with the
strong element, and text marked or highlighted should use the mark
element.
The following would be incorrect usage:
<p><b>WARNING!</b> Do not frob the barbinator!</p>
In the previous example, the correct element to use would have been strong, not
b.
Style sheets can be used to format b elements, just like any other
element can be restyled. Thus, it is not the case that content in b elements will
necessarily be boldened.
The u element represents a span of text with an unarticulated, though
explicitly rendered, non-textual annotation, such as labeling the text as being a proper name in
Chinese text (a Chinese proper name mark), or labeling the text as being misspelt.
In most cases, another element is likely to be more appropriate: for marking stress emphasis,
the em element should be used; for marking key words or phrases either the
b element or the mark element should be used, depending on the context;
for marking book titles, the cite element should be used; for labeling text with explicit textual annotations, the
ruby element should be used; for technical terms, taxonomic designation,
transliteration, a thought, or for labeling ship names in Western texts, the i
element should be used.
The default rendering of the u element in visual presentations
clashes with the conventional rendering of hyperlinks (underlining). Authors are encouraged to
avoid using the u element where it could be confused for a hyperlink.
In this example, a u element is used to mark a word as misspelt:
The mark element represents a run of text in one document marked or
highlighted for reference purposes, due to its relevance in another context. When used in a
quotation or other block of text referred to from the prose, it indicates a highlight that was not
originally present but which has been added to bring the reader's attention to a part of the text
that might not have been considered important by the original author when the block was originally
written, but which is now under previously unexpected scrutiny. When used in the main prose of a
document, it indicates a part of the document that has been highlighted due to its likely
relevance to the user's current activity.
This example shows how the mark element can be used to bring attention to a
particular part of a quotation:
<p lang="en-US">Consider the following quote:</p>
<blockquote lang="en-GB">
<p>Look around and you will find, no-one's really
<mark>colour</mark> blind.</p>
</blockquote>
<p lang="en-US">As we can tell from the <em>spelling</em> of the word,
the person writing this quote is clearly not American.</p>
(If the goal was to mark the element as misspelt, however, the u element,
possibly with a class, would be more appropriate.)
Another example of the mark element is highlighting parts of a document that are
matching some search string. If someone looked at a document, and the server knew that the user
was searching for the word "kitten", then the server might return the document with one paragraph
modified as follows:
<p>I also have some <mark>kitten</mark>s who are visiting me
these days. They're really cute. I think they like my garden! Maybe I
should adopt a <mark>kitten</mark>.</p>
In the following snippet, a paragraph of text refers to a specific part of a code
fragment.
<p>The highlighted part below is where the error lies:</p>
<pre><code>var i: Integer;
begin
i := <mark>1.1</mark>;
end.</code></pre>
This is separate from syntax highlighting, for which span is more
appropriate. Combining both, one would get:
<p>The highlighted part below is where the error lies:</p>
<pre><code><span class=keyword>var</span> <span class=ident>i</span>: <span class=type>Integer</span>;
<span class=keyword>begin</span>
<span class=ident>i</span> := <span class=literal><mark>1.1</mark></span>;
<span class=keyword>end</span>.</code></pre>
This is another example showing the use of mark to highlight a part of quoted
text that was originally not emphasized. In this example, common typographic conventions have led
the author to explicitly style mark elements in quotes to render in italics.
<style>
blockquote mark, q mark {
font: inherit; font-style: italic;
text-decoration: none;
background: transparent; color: inherit;
}
.bubble em {
font: inherit; font-size: larger;
text-decoration: underline;
}
</style>
<article>
<h1>She knew</h1>
<p>Did you notice the subtle joke in the joke on panel 4?</p>
<blockquote>
<p class="bubble">I didn't <em>want</em> to believe. <mark>Of course
on some level I realized it was a known-plaintext attack.</mark> But I
couldn't admit it until I saw for myself.</p>
</blockquote>
<p>(Emphasis mine.) I thought that was great. It's so pedantic, yet it
explains everything neatly.</p>
</article>
Note, incidentally, the distinction between the em element in this example, which
is part of the original text being quoted, and the mark element, which is
highlighting a part for comment.
The following example shows the difference between denoting the importance of a span
of text (strong) as opposed to denoting the relevance of a span of text
(mark). It is an extract from a textbook, where the extract has had the parts
relevant to the exam highlighted. The safety warnings, important though they may be, are
apparently not relevant to the exam.
<h3>Wormhole Physics Introduction</h3>
<p><mark>A wormhole in normal conditions can be held open for a
maximum of just under 39 minutes.</mark> Conditions that can increase
the time include a powerful energy source coupled to one or both of
the gates connecting the wormhole, and a large gravity well (such as a
black hole).</p>
<p><mark>Momentum is preserved across the wormhole. Electromagnetic
radiation can travel in both directions through a wormhole,
but matter cannot.</mark></p>
<p>When a wormhole is created, a vortex normally forms.
<strong>Warning: The vortex caused by the wormhole opening will
annihilate anything in its path.</strong> Vortexes can be avoided when
using sufficiently advanced dialing technology.</p>
<p><mark>An obstruction in a gate will prevent it from accepting a
wormhole connection.</mark></p>
This element is especially useful when embedding user-generated content with an unknown
directionality.
In this example, usernames are shown along with the number of posts that the user has
submitted. If the bdi element were not used, the username of the Arabic user would
end up confusing the text (the bidirectional algorithm would put the colon and the number "3"
next to the word "User" rather than next to the word "posts").
When using the bdi element, the username acts as expected.If the bdi element were to be replaced by a b element, the username would confuse the bidirectional algorithm and the third bullet would end up saying "User 3 :", followed by the Arabic name (right-to-left), followed by "posts" and a period.
The bdo element represents explicit text directionality formatting
control for its children. It allows authors to override the Unicode bidirectional algorithm by
explicitly specifying a direction override. [BIDI]
Authors must specify the dir attribute on this element, with the
value ltr to specify a left-to-right override and with the value rtl to
specify a right-to-left override. The auto value must not be specified.
In this example, a code fragment is marked up using span elements and class attributes so that its keywords and identifiers can be
color-coded from CSS:
While line breaks are usually represented in visual media by physically moving
subsequent text to a new line, a style sheet or user agent would be equally justified in causing
line breaks to be rendered in a different manner, for instance as green dots, or as extra
spacing.
br elements must be used only for line breaks that are actually part of the
content, as in poems or addresses.
The following example is correct usage of the br element:
<p>P. Sherman<br>
42 Wallaby Way<br>
Sydney</p>
br elements must not be used for separating thematic groups in a paragraph.
The following examples are non-conforming, as they abuse the br element:
<p><a ...>34 comments.</a><br>
<a ...>Add a comment.</a></p>
If a paragraph consists of nothing but a single br element, it
represents a placeholder blank line (e.g. as in a template). Such blank lines must not be used for
presentation purposes.
Any content inside br elements must not be considered part of the surrounding
text.
The wbr element represents a line break opportunity.
In the following example, someone is quoted as saying something which, for effect, is written
as one long word. However, to ensure that the text can be wrapped in a readable fashion, the
individual words in the quote are separated using a wbr element.
<p>So then she pointed at the tiger and screamed
"there<wbr>is<wbr>no<wbr>way<wbr>you<wbr>are<wbr>ever<wbr>going<wbr>to<wbr>catch<wbr>me"!</p>
Any content inside wbr elements must not be considered part of the surrounding
text.
var wbr = document.createElement("wbr");
wbr.textContent = "This is wrong";
document.body.appendChild(wbr);
Links are a conceptual construct, created by a, area, and
link elements, that represent a connection between
two resources, one of which is the current Document. There are two kinds of links in
HTML:
Links to
external resources
These are links to resources that are to be used to augment the current document,
generally automatically processed by the user agent.
Hyperlinks
These are links to other resources that are generally exposed to the user by the user
agent so that the user can cause the user agent to navigate to those resources, e.g.
to visit them in a browser or download them.
For link elements with an href attribute and a
rel attribute, links must be created for the keywords of the
rel attribute, as defined for those keywords in the link types section.
Similarly, for a and area elements with an href attribute and a rel attribute, links must be created for the keywords of the
rel attribute as defined for those keywords in the link types section. Unlike link elements, however,
a and area elements with an href
attribute that either do not have a rel attribute, or
whose rel attribute has no keywords that are defined as
specifying hyperlinks, must also create a hyperlink.
This implied hyperlink has no special meaning (it has no link type)
beyond linking the element's node document to the resource given by the element's href attribute.
A hyperlink can have one or more hyperlink
annotations that modify the processing semantics of that hyperlink.
When an a or area element's activation behavior is
invoked, the user agent may allow the user to indicate a preference regarding whether the
hyperlink is to be used for navigation or whether the resource it
specifies is to be downloaded.
In the absence of a user preference, the default should be navigation if the element has no
download attribute, and should be to download the
specified resource if it does.
Whether determined by the user's preferences or via the presence or absence of the attribute,
if the decision is to use the hyperlink for navigation then the user
agent must follow the hyperlink, and if the decision is
to use the hyperlink to download a resource, the user agent must download the hyperlink. These terms are defined in subsequent sections
below.
The download attribute, if present,
indicates that the author intends the hyperlink to be used for downloading a resource. The attribute may have a value; the value, if any,
specifies the default file name that the author recommends for use in labeling the resource in a
local file system. There are no restrictions on allowed values, but authors are cautioned that
most file systems have limitations with regard to what punctuation is supported in file names,
and user agents are likely to adjust file names accordingly.
Other specifications may add HTML link types as
defined in Other link types. These specifications may require
that their link types be included in rel's supported
tokens.
The rel attribute has no default value. If the
attribute is omitted or if none of the values in the attribute are recognized by the user agent,
then the document has no particular relationship with the destination resource other than there
being a hyperlink between the two.
The hreflang attribute on
a elements that create hyperlinks, if present, gives
the language of the linked resource. It is purely advisory. The value must be a valid BCP 47
language tag. [BCP47] User agents must not consider this attribute
authoritative — upon fetching the resource, user agents must use only language information
associated with the resource to determine its language, not metadata included in the link to the
resource.
The type attribute, if present, gives the
MIME type of the linked resource. It is purely advisory. The value must be a
valid MIME type. User agents must not consider the type attribute authoritative — upon fetching the
resource, user agents must not use metadata included in the link to the resource to determine its
type.
Returns the hyperlink's URL's fragment (includes leading "#" if
non-empty).
Can be set, to change the URL's fragment (ignores leading "#").
An element implementing the HTMLHyperlinkElementUtils mixin has an associated url (null or a URL). It is initially null.
An element implementing the HTMLHyperlinkElementUtils mixin has an associated set the url algorithm, which runs these steps:
If this element's href content attribute is
absent, set this element's url to null.
Otherwise, parse this element's href content
attribute value relative to this element's node document. If parsing is successful, set this element's url to the result; otherwise, set this element's
url to null.
When elements implementing the HTMLHyperlinkElementUtils mixin are created, and
whenever those elements have their href content
attribute set, changed, or removed, the user agent must set the url.
Because the URL parser ignores multiple consecutive colons, providing a value
of "https:" (or even "https::::") is the same as
providing a value of "https".
Otherwise, if parsing the URL failed, the
user agent may report the error to the user in a user-agent-specific manner, may queue a
task to navigate the targetbrowsing context to an error page to report the error, or may ignore the error and
do nothing. In any case, the user agent must then abort these steps.
If there is a hyperlink suffix, append it to URL.
Let resource be a new request whose url is URL and whose referrer policy is the current state of
subject's referrerpolicy content attribute.
In some cases, resources are intended for later use rather than immediate viewing. To indicate
that a resource is intended to be downloaded for use later, rather than immediately used, the
download attribute can be specified on the
a or area element that creates the hyperlink to that
resource.
The attribute can furthermore be given a value, to specify the file name that user agents are
to use when storing the resource in a file system. This value can be overridden by the `Content-Disposition` HTTP header's filename parameters.
[RFC6266]
In cross-origin situations, the download
attribute has to be combined with the `Content-Disposition` HTTP header, specifically with the
attachment disposition type, to avoid the user being warned of possibly
nefarious activity. (This is to protect users from being made to download sensitive personal or
confidential information without their full understanding.)
When a user downloads a hyperlink created by an
element subject, optionally with a hyperlink suffix, the user agent must
run the following steps:
If parsing the URL fails, the user agent
may report the error to the user in a user-agent-specific manner, may
navigate to an error page to report the error, or may
ignore the error and do nothing. In either case, the user agent must abort these steps.
When a user agent is to handle a resource obtained from a fetch as a download, it
should provide the user with a way to save the resource for later use, if a resource is
successfully obtained; or otherwise should report any problems downloading the file to the
user.
If the user agent needs a file name for a resource being handled as a download, it
should select one using the following algorithm.
This algorithm is intended to mitigate security dangers involved in downloading
files from untrusted sites, and user agents are strongly urged to follow it.
Let filename be the void value.
If the resource has a `Content-Disposition`
header, that header specifies the attachment disposition type, and the
header includes file name information, then let filename have the value
specified by the header, and jump to the step labeled sanitize below. [RFC6266]
Let interface origin be the origin of the
Document in which the download or
navigate action resulting in the download was initiated, if any.
Let resource origin be the origin of the URL of the
resource being downloaded, unless that URL's scheme
component is data, in which case let resource origin be
the same as the interface origin, if any.
If there is no interface origin, then let trusted
operation be true. Otherwise, let trusted operation be true if resource origin is the same origin as interface
origin, and false otherwise.
If trusted operation is true and the resource has a `Content-Disposition` header and that header includes file
name information, then let filename have the value specified by the header,
and jump to the step labeled sanitize below. [RFC6266]
If the download was not initiated from a hyperlink created by an
a or area element, or if the element of the hyperlink from
which it was initiated did not have a download
attribute when the download was initiated, or if there was such an attribute but its value when
the download was initiated was the empty string, then jump to the step labeled no proposed
file name.
Let proposed filename have the value of the download attribute of the element of the
hyperlink that initiated the download at the time the download was
initiated.
If trusted operation is true, let filename have
the value of proposed filename, and jump to the step labeled sanitize
below.
If the resource has a `Content-Disposition`
header and that header specifies the attachment disposition type, let filename have the value of proposed filename, and jump to the
step labeled sanitize below. [RFC6266]
No proposed file name: If trusted operation is true, or if the
user indicated a preference for having the resource in question downloaded, let filename have a value derived from the URL of the resource in a
user-agent-defined manner, and jump to the step labeled sanitize below.
Act in a user-agent-defined manner to safeguard the user from a potentially hostile
cross-origin download. If the download is not to be aborted, then let filename be set to the user's preferred file name or to a file name selected by
the user agent, and jump to the step labeled sanitize below.
If the algorithm reaches this step, then a download was begun from a different origin than
the resource being downloaded, and the origin did not mark the file as suitable for
downloading, and the download was not initiated by the user. This could be because a download attribute was used to trigger the download, or
because the resource in question is not of a type that the user agent supports.
This could be dangerous, because, for instance, a hostile server could be trying to get a
user to unknowingly download private information and then re-upload it to the hostile server,
by tricking the user into thinking the data is from the hostile server.
Thus, it is in the user's interests that the user be somehow notified that the resource in
question comes from quite a different source, and to prevent confusion, any suggested file name
from the potentially hostile interface origin should be ignored.
Sanitize: Optionally, allow the user to influence filename. For
example, a user agent could prompt the user for a file name, potentially providing the value of
filename as determined above as a default value.
Adjust filename to be suitable for the local file system.
For example, this could involve removing characters that are not legal in
file names, or trimming leading and trailing whitespace.
If the platform conventions do not in any way use extensions to determine the types of file on the file system,
then return filename as the file name and abort these steps.
Let claimed type be the type given by the resource's Content-Type metadata, if any is known. Let named
type be the type given by filename's extension, if any is known. For the purposes of this step, a
type is a mapping of a MIME type to an extension.
If named type is consistent with the user's preferences (e.g. because
the value of filename was determined by prompting the user), then return filename as the file name and abort these steps.
If claimed type and named type are the same type
(i.e. the type given by the resource's Content-Type metadata is
consistent with the type given by filename's extension), then return filename as the file
name and abort these steps.
If the claimed type is known, then alter filename to
add an extension corresponding to claimed
type.
Otherwise, if named type is known to be potentially dangerous (e.g. it
will be treated by the platform conventions as a native executable, shell script, HTML
application, or executable-macro-capable document) then optionally alter filename to add a known-safe extension
(e.g. ".txt").
This last step would make it impossible to download executables, which might not
be desirable. As always, implementors are forced to balance security and usability in this
matter.
Return filename as the file name.
For the purposes of this algorithm, a file extension
consists of any part of the file name that platform conventions dictate will be used for
identifying the type of the file. For example, many operating systems use the part of the file
name following the last dot (".") in the file name to determine the type of
the file, and from that the manner in which the file is to be opened or executed.
User agents should ignore any directory or path information provided by the resource itself,
its URL, and any download attribute, in
deciding where to store the resulting file in the user's file system.
If a hyperlink created by an a or area element has a
ping attribute, and the user follows the hyperlink, and
the value of the element's href attribute can be parsed, relative to the element's node document, without
failure, then the user agent must take the ping
attribute's value, split that string on ASCII
whitespace, parse each resulting token relative to the
element's node document, and then run these substeps for each resulting URL
recordping URL, ignoring tokens that fail to parse:
Optionally, abort these steps. (For example, the user agent might wish to ignore any or
all ping URLs in accordance with the user's expressed preferences.)
Let target URL be the resulting URL string obtained from parsing the value of the element's href attribute and then run these substeps:
If the URL of the Document object
containing the hyperlink being audited and ping URL have the same
origin
If the origins are different, but the HTTPS
state of the Document containing the hyperlink being audited is "none"
request must include a `Ping-From` header
with, as its value, the URL of the document
containing the hyperlink, and a `Ping-To` HTTP header with,
as its value, the target URL.
Otherwise
request must include a `Ping-To` HTTP header
with, as its value, target URL. request does not
include a `Ping-From` header.
This may be done in parallel with the primary fetch, and is independent of the
result of that fetch.
User agents should allow the user to adjust this behavior, for example in conjunction with a
setting that disables the sending of HTTP `Referer` (sic)
headers. Based on the user's preferences, UAs may either ignore the ping attribute altogether, or selectively ignore URLs in the
list (e.g. ignoring any third-party URLs); this is explicitly accounted for in the steps
above.
User agents must ignore any entity bodies returned in the responses. User agents may close the
connection prematurely once they start receiving a response body.
When the ping attribute is present, user agents
should clearly indicate to the user that following the hyperlink will also cause secondary
requests to be sent in the background, possibly including listing the actual target URLs.
For example, a visual user agent could include the hostnames of the target ping
URLs along with the hyperlink's actual URL in a status bar or tooltip.
The ping attribute is redundant with pre-existing
technologies like HTTP redirects and JavaScript in allowing Web pages to track which off-site
links are most popular or allowing advertisers to track click-through rates.
However, the ping attribute provides these advantages
to the user over those alternatives:
It allows the user to see the final target URL unobscured.
It allows the UA to inform the user about the out-of-band notifications.
It allows the user to disable the notifications without losing the underlying link
functionality.
It allows the UA to optimize the use of available network bandwidth so that the target page
loads faster.
Thus, while it is possible to track users without this feature, authors are encouraged to use
the ping attribute so that the user agent can make the
user experience more transparent.
4.6.6 Link types
The following table summarizes the link types that are defined by this specification, by their
corresponding keywords. This table is non-normative; the actual definitions for the link types are
given in the next few sections.
In this section, the term referenced document refers to the resource identified by the
element representing the link, and the term current document refers to the resource within
which the element representing the link finds itself.
To determine which link types apply to a link, a, or
area element, the element's rel attribute must be split on ASCII whitespace. The resulting tokens
are the keywords for the link types that apply to that element.
Except where otherwise specified, a keyword must not be specified more than once per rel attribute.
Some of the sections that follow the table below list synonyms for certain keywords. The
indicated synonyms are to be handled as specified by user agents, but must
not be used in documents (for example, the keyword "copyright").
Specifies that the user agent must preemptively fetch and cache the target resource for current navigation according to the destination given by the as attribute (and the priority associated with that destination).
Specifies that the user agent should preemptively fetch the target resource and process it in a way that helps deliver a faster response in the future.
The meaning of this keyword depends on the values of the other attributes.
If the element is a link element and the rel
attribute also contains the keyword stylesheet
The alternate keyword modifies the meaning of the stylesheet keyword in the way described for that keyword. The
alternate keyword does not create a link of its own.
If the alternate keyword is used with the type attribute set to the value application/rss+xml or the value application/atom+xml
The keyword creates a hyperlink referencing a syndication feed (though not
necessarily syndicating exactly the same content as the current page).
For the purposes of feed autodiscovery, user agents should consider all link
elements in the document with the alternate keyword used and
with their type attribute set to the value application/rss+xml or the value application/atom+xml. If the user agent has the concept of a default
syndication feed, the first such element (in tree order) should be used as the
default.
The following link elements give syndication feeds for a blog:
Such link elements would be used by user agents engaged in feed autodiscovery,
with the first being the default (where applicable).
The following example offers various different syndication feeds to the user, using
a elements:
<p>You can access the planets database using Atom feeds:</p>
<ul>
<li><a href="recently-visited-planets.xml" rel="alternate" type="application/atom+xml">Recently Visited Planets</a></li>
<li><a href="known-bad-planets.xml" rel="alternate" type="application/atom+xml">Known Bad Planets</a></li>
<li><a href="unexplored-planets.xml" rel="alternate" type="application/atom+xml">Unexplored Planets</a></li>
</ul>
These links would not be used in feed autodiscovery.
Otherwise
The keyword creates a hyperlink referencing an alternate representation of the
current document.
The nature of the referenced document is given by the hreflang, and type attributes.
If the alternate keyword is used with the hreflang attribute, and that attribute's value differs
from the document element's language, it indicates that the referenced
document is a translation.
If the alternate keyword is used with the type attribute, it indicates that the referenced document is
a reformulation of the current document in the specified format.
The hreflang and type attributes can be combined when specified with the alternate keyword.
For example, the following link is a French translation that uses the PDF format:
This relationship is transitive — that is, if a document links to two other documents
with the link type "alternate", then, in addition to implying
that those documents are alternative representations of the first document, it is also implying
that those two documents are alternative representations of each other.
4.6.6.2 Link type "author"
The author keyword may be used with link,
a, and area elements. This keyword creates a hyperlink.
For a and area elements, the author
keyword indicates that the referenced document provides further information about the author of
the nearest article element ancestor of the element defining the hyperlink, if there
is one, or of the page as a whole, otherwise.
For link elements, the author keyword indicates
that the referenced document provides further information about the author for the page as a
whole.
The "referenced document" can be, and often is, a mailto: URL giving the e-mail address of the author. [MAILTO]
Synonyms: For historical reasons, user agents must also treat
link, a, and area elements that have a rev attribute with the value "made" as having the author keyword specified as a link relationship.
4.6.6.3 Link type "bookmark"
The bookmark keyword may be used with a and
area elements. This keyword creates a hyperlink.
The following snippet has three permalinks. A user agent could determine which permalink
applies to which part of the spec by looking at where the permalinks are given.
...
<body>
<h1>Example of permalinks</h1>
<div id="a">
<h2>First example</h2>
<p><a href="a.html" rel="bookmark">This permalink applies to
only the content from the first H2 to the second H2</a>. The DIV isn't
exactly that section, but it roughly corresponds to it.</p>
</div>
<h2>Second example</h2>
<article id="b">
<p><a href="b.html" rel="bookmark">This permalink applies to
the outer ARTICLE element</a> (which could be, e.g., a blog post).</p>
<article id="c">
<p><a href="c.html" rel="bookmark">This permalink applies to
the inner ARTICLE element</a> (which could be, e.g., a blog comment).</p>
</article>
</article>
</body>
...
The dns-prefetch keyword indicates that preemptively
performing DNS resolution for the origin of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
origin, and the user experience would be improved by preempting the latency costs
associated with DNS resolution. User agents must implement the processing model of
the dns-prefetch keyword described in the Resource
Hints specification. [RESOURCEHINTS]
There is no default type for resources given by the dns-prefetch keyword.
4.6.6.5 Link type "external"
The external keyword may be used with a and
area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the
implied hyperlink, if no other keywords create one).
The external keyword indicates that the link is leading to a
document that is not part of the site that the current document forms a part of.
4.6.6.6 Link type "help"
The help keyword may be used with link,
a, and area elements. This keyword creates a hyperlink.
For a and area elements, the help
keyword indicates that the referenced document provides further help information for the parent of
the element defining the hyperlink, and its children.
In the following example, the form control has associated context-sensitive help. The user
agent could use this information, for example, displaying the referenced document if the user
presses the "Help" or "F1" key.
The specified resource is an icon representing the page or site, and should be used by the user
agent when representing the page in the user interface.
Icons could be auditory icons, visual icons, or other kinds of icons. If
multiple icons are provided, the user agent must select the most appropriate icon according to the
type, media, and sizes attributes. If there are multiple equally appropriate icons,
user agents must use the last one declared in tree order at the time that the user
agent collected the list of icons. If the user agent tries to use an icon but that icon is
determined, upon closer examination, to in fact be inappropriate (e.g. because it uses an
unsupported format), then the user agent must try the next-most-appropriate icon as determined by
the attributes.
User agents are not required to update icons when the list of icons changes, but
are encouraged to do so.
There is no default type for resources given by the icon keyword.
However, for the purposes of determining the type of the
resource, user agents must expect the resource to be an image.
The sizes attribute gives the sizes of icons
for visual media. Its value, if present, is merely advisory. User agents may use the value to
decide which icon(s) to use if multiple icons are available.
The keywords represent icon sizes in raw pixels (as opposed to CSS
pixels).
An icon that is 50 CSS pixels wide intended for
displays with a device pixel density of two device pixels per CSS pixel
(2x, 192dpi) would have a width of 100 raw pixels. This feature does not support indicating that a
different resource is to be used for small high-resolution icons vs large low-resolution icons
(e.g. 50×50 2x vs 100×100 1x).
To parse and process the attribute's value, the user agent must first split the attribute's value on ASCII whitespace, and must then
parse each resulting keyword to determine what it represents.
The any keyword represents that the
resource contains a scalable icon, e.g. as provided by an SVG image.
Other keywords must be further parsed as follows to determine what they represent:
If the keyword doesn't contain exactly one U+0078 LATIN SMALL LETTER X or U+0058 LATIN
CAPITAL LETTER X character, then this keyword doesn't represent anything. Abort these steps for
that keyword.
Let width string be the string before the "x" or
"X".
Let height string be the string after the "x" or
"X".
If either width string or height string start with
a U+0030 DIGIT ZERO (0) character or contain any characters other than ASCII digits,
then this keyword doesn't represent anything. Abort these steps for that keyword.
For historical reasons, the icon keyword may be preceded by the
keyword "shortcut". If the "shortcut" keyword is
present, the rel attribute's entire value must be an
ASCII case-insensitive match for the string "shortcut icon" (with a single U+0020 SPACE character between the tokens and
no other ASCII whitespace).
The license keyword indicates that the referenced document
provides the copyright license terms under which the main content of the current document is
provided.
This specification does not specify how to distinguish between the main content of a document
and content that is not deemed to be part of that main content. The distinction should be made
clear to the user.
Consider a photo sharing site. A page on that site might describe and show a photograph, and
the page might be marked up as follows:
In this case the license applies to just the photo (the main
content of the document), not the whole document. In particular not the design of the page
itself, which is covered by the copyright given at the bottom of the document. This could be made
clearer in the styling (e.g. making the license link prominently positioned near the photograph,
while having the page copyright in light small text at the foot of the page).
Synonyms: For historical reasons, user agents must also treat the keyword
"copyright" like the license keyword.
4.6.6.9 Link type "nofollow"
The nofollow keyword may be used with a and
area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the
implied hyperlink, if no other keywords create one).
The nofollow keyword indicates that the link is not endorsed
by the original author or publisher of the page, or that the link to the referenced document was
included primarily because of a commercial relationship between people affiliated with the two
pages.
4.6.6.10 Link type "noreferrer"
The noreferrer keyword may be used with a and
area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the
implied hyperlink, if no other keywords create one).
It indicates that no referrer information is to be leaked when following the link.
If a user agent follows a link defined by an a or area element that
has the noreferrer keyword, the user agent must set their
request's referrer to "no-referrer".
For historical reasons, the noreferrer
keyword implies the behavior associated with the noopener
keyword when present on a hyperlink that creates a new browsing context. That is, <a
href="..." rel="noreferrer" target="_blank"> has the same behavior as <a href="..." rel="noreferrer noopener" target="_blank">.
4.6.6.11 Link type "noopener"
Support: rel-noopenerChrome for Android56+Chrome49+UC Browser for AndroidNoneiOS SafariNoneFirefox52+IENoneSamsung InternetNoneOpera MiniNoneAndroid Browser53+Safari10.1+EdgeNoneOpera36+
The noopener keyword may be used with a and
area elements. This keyword does not create a hyperlink, but annotates any other hyperlinks created by the element (the
implied hyperlink, if no other keywords create one).
The preconnect keyword indicates that preemptively
initiating a connection to the origin of the specified resource is likely to be
beneficial, as it is highly likely that the user will require resources located at that
origin, and the user experience would be improved by preempting the latency costs
associated with establishing the connection. User agents must implement the
processing model of the preconnect keyword described in
Resource Hints. [RESOURCEHINTS]
There is no default type for resources given by the preconnect keyword.
The prefetch keyword indicates that preemptively fetching and caching the specified resource is likely to be
beneficial, as it is highly likely that the user will require this resource for future
navigations. User agents must implement the processing model of the prefetch keyword described in Resource Hints.
[RESOURCEHINTS]
There is no default type for resources given by the prefetch
keyword.
The preload keyword indicates that the user agent must
preemptively fetch and cache the specified resource according
to the destination given by the as attribute (and the priority associated with that destination), as it is highly likely that the user
will require this resource for the current navigation. User agents must implement
the processing model of the preload keyword described in
Preload. [PRELOAD]
There is no default type for resources given by the preload
keyword.
The prerender keyword indicates that the specified resource
might be required by the next navigation, and so it may be beneficial to not only preemptively
fetch the resource, but also to process it, e.g. by fetching its subresources or performing some rendering. User agents must implement the processing model of the prerender keyword described in Resource Hints.
[RESOURCEHINTS]
There is no default type for resources given by the prerender keyword.
4.6.6.17 Link type "search"
The search keyword may be used with link,
a, and area elements. This keyword creates a hyperlink.
The search keyword indicates that the referenced document
provides an interface specifically for searching the document and its related resources.
OpenSearch description documents can be used with link elements and
the search link type to enable user agents to autodiscover search
interfaces. [OPENSEARCH]
The stylesheet keyword may be used with link
elements. This keyword creates an external resource
link that contributes to the styling processing model. This keyword is
body-ok.
The specified resource is a resource that describes how to present the document. Exactly how
the resource is to be processed depends on the actual type of the resource.
If the alternate keyword is also specified on the
link element, then the link is an alternative stylesheet; in this case,
the title attribute must be specified on the link
element, with a non-empty value.
The default type for resources given by the stylesheet
keyword is text/css.
Quirk: If the document has been set to quirks mode, has the
same origin as the URL of the external resource,
and the Content-Type metadata of the external resource is not a
supported style sheet type, the user agent must instead assume it to be text/css.
If element no longer creates an external resource link
that contributes to the styling processing model, or if, since the resource in question was obtained, it has become appropriate to obtain it again (meaning this algorithm is about to be
invoked again for a newly obtained resource), then abort these steps.
This is a reference to the (possibly absent at this time) attribute, rather
than a copy of the attribute's current value. The CSSOM specification defines what happens
when the attribute is dynamically set, changed, or removed.
If the element has a charset attribute, get an encoding from that attribute's value. If that
succeeds, return the resulting encoding and abort these steps. [ENCODING]
The tag keyword may be used with a and
area elements. This keyword creates a hyperlink.
The tag keyword indicates that the tag that the
referenced document represents applies to the current document.
Since it indicates that the tag applies to the current document, it would
be inappropriate to use this keyword in the markup of a tag cloud, which
lists the popular tags across a set of pages.
This document is about some gems, and so it is tagged with "https://en.wikipedia.org/wiki/Gemstone" to unambiguously categorize it as applying
to the "jewel" kind of gems, and not to, say, the towns in the US, the Ruby package format, or
the Swiss locomotive class:
<!DOCTYPE HTML>
<html lang="en">
<head>
<title>My Precious</title>
</head>
<body>
<header><h1>My precious</h1> <p>Summer 2012</p></header>
<p>Recently I managed to dispose of a red gem that had been
bothering me. I now have a much nicer blue sapphire.</p>
<p>The red gem had been found in a bauxite stone while I was digging
out the office level, but nobody was willing to haul it away. The
same red gem stayed there for literally years.</p>
<footer>
Tags: <a rel=tag href="https://en.wikipedia.org/wiki/Gemstone">Gemstone</a>
</footer>
</body>
</html>
In this document, there are two articles. The "tag"
link, however, applies to the whole page (and would do so wherever it was placed, including if it
was within the article elements).
<!DOCTYPE HTML>
<html lang="en">
<head>
<title>Gem 4/4</title>
</head>
<body>
<article>
<h1>801: Steinbock</h1>
<p>The number 801 Gem 4/4 electro-diesel has an ibex and was rebuilt in 2002.</p>
</article>
<article>
<h1>802: Murmeltier</h1>
<figure>
<img src="https://upload.wikimedia.org/wikipedia/commons/b/b0/Trains_de_la_Bernina_en_hiver_2.jpg"
alt="The 802 was red with pantographs and tall vents on the side.">
<figcaption>The 802 in the 1980s, above Lago Bianco.</figcaption>
</figure>
<p>The number 802 Gem 4/4 electro-diesel has a marmot and was rebuilt in 2003.</p>
</article>
<p class="topic"><a rel=tag href="https://en.wikipedia.org/wiki/Rhaetian_Railway_Gem_4/4">Gem 4/4</a></p>
</body>
</html>
4.6.6.21 Sequential link types
Some documents form part of a sequence of documents.
A sequence of documents is one where each document can have a previous sibling and a
next sibling. A document with no previous sibling is the start of its sequence, a
document with no next sibling is the end of its sequence.
A document may be part of multiple sequences.
4.6.6.21.1 Link type "next"
The next keyword may be used with link,
a, and area elements. This keyword creates a hyperlink.
The next keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the next logical document in the
sequence.
When the next keyword is used with a link
element, user agents should implement one of the processing models described in Resource
Hints, i.e. should process such links as if they were using one of the dns-prefetch, preconnect,
prefetch, or prerender
keywords. Which resource hint the user agent wishes to use is implementation-dependent; for
example, a user agent may wish to use the less-costly preconnect hint when trying to conserve data, battery power, or
processing power, or may wish to pick a resource hint depending on heuristic analysis of past
user behavior in similar scenarios. [RESOURCEHINTS]
4.6.6.21.2 Link type "prev"
The prev keyword may be used with link,
a, and area elements. This keyword creates a hyperlink.
The prev keyword indicates that the document is part of a
sequence, and that the link is leading to the document that is the previous logical document in
the sequence.
Synonyms: For historical reasons, user agents must also treat the keyword
"previous" like the prev keyword.
Anyone is free to edit the microformats wiki existing-rel-values page at
any time to add a type. Extension types must be specified with the following information:
Keyword
The actual value being defined. The value should not be confusingly similar to any other
defined value (e.g. differing only in case).
If the value contains a U+003A COLON character (:), it must also be an absolute
URL.
The keyword may be specified on a and area elements; it annotates other hyperlinks
created by the element.
Brief description
A short non-normative description of what the keyword's meaning is.
Specification
A link to a more detailed description of the keyword's semantics and requirements. It
could be another page on the Wiki, or a link to an external page.
Synonyms
A list of other keyword values that have exactly the same processing requirements. Authors
should not use the values defined to be synonyms, they are only intended to allow user agents to
support legacy content. Anyone may remove synonyms that are not used in practice; only names that
need to be processed as synonyms for compatibility with legacy content are to be registered in
this way.
Status
One of the following:
Proposed
The keyword has not received wide peer review and approval. Someone has proposed it and is,
or soon will be, using it.
Ratified
The keyword has received wide peer review and approval. It has a specification that
unambiguously defines how to handle pages that use the keyword, including when they use it in
incorrect ways.
Discontinued
The keyword has received wide peer review and it has been found wanting. Existing pages are
using this keyword, but new pages should avoid it. The "brief description" and "specification"
entries will give details of what authors should use instead, if anything.
If a keyword is found to be redundant with existing values, it should be removed and listed
as a synonym for the existing value.
If a keyword is registered in the "proposed" state for a period of a month or more without
being used or specified, then it may be removed from the registry.
If a keyword is added with the "proposed" status and found to be redundant with existing
values, it should be removed and listed as a synonym for the existing value. If a keyword is
added with the "proposed" status and found to be harmful, then it should be changed to
"discontinued" status.
Anyone can change the status at any time, but should only do so in accordance with the
definitions above.
Conformance checkers must use the information given on the microformats wiki
existing-rel-values page to establish if a value is allowed or not: values defined in this
specification or marked as "proposed" or "ratified" must be accepted when used on the elements for
which they apply as described in the "Effect on..." field, whereas values marked as "discontinued"
or not listed in either this specification or on the aforementioned page must be rejected as
invalid. Conformance checkers may cache this information (e.g. for performance reasons or to avoid
the use of unreliable network connectivity).
When an author uses a new type not defined by either this specification or the Wiki page,
conformance checkers should offer to add the value to the Wiki, with the details described above,
with the "proposed" status.
Types defined as extensions in the microformats
wiki existing-rel-values page with the status "proposed" or "ratified" may be used with the
rel attribute on link, a, and area
elements in accordance to the "Effect on..." field. [MFREL]
4.7 Edits
The ins and del elements represent edits to the document.
The following example represents the addition of two paragraphs, the second of which was
inserted in two parts. The first ins element in this example thus crosses a
paragraph boundary, which is considered poor form.
<aside>
<!-- don't do this -->
<ins datetime="2005-03-16 00:00Z">
<p> I like fruit. </p>
Apples are <em>tasty</em>.
</ins>
<ins datetime="2007-12-19 00:00Z">
So are pears.
</ins>
</aside>
Here is a better way of marking this up. It uses more elements, but none of the elements cross
implied paragraph boundaries.
<aside>
<ins datetime="2005-03-16 00:00Z">
<p> I like fruit. </p>
</ins>
<ins datetime="2005-03-16 00:00Z">
Apples are <em>tasty</em>.
</ins>
<ins datetime="2007-12-19 00:00Z">
So are pears.
</ins>
</aside>
The following shows a "to do" list where items that have been done are crossed-off with the
date and time of their completion.
<h1>To Do</h1>
<ul>
<li>Empty the dishwasher</li>
<li><del datetime="2009-10-11T01:25-07:00">Watch Walter Lewin's lectures</del></li>
<li><del datetime="2009-10-10T23:38-07:00">Download more tracks</del></li>
<li>Buy a printer</li>
</ul>
The cite attribute may be used to specify the
URL of a document that explains the change. When that
document is long, for instance the minutes of a meeting, authors are encouraged to include a fragment pointing to the specific part of that document that
discusses the change.
If the cite attribute is present, it must be a valid
URL potentially surrounded by spaces that explains the change. 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 edits), not for readers.
The datetime attribute may be used to specify
the time and date of the change.
User agents must parse the datetime attribute according
to the parse a date or time string algorithm. If that doesn't return a date or a global date and time,
then the modification has no associated timestamp (the value is non-conforming; it is not a
valid date string with optional time). Otherwise, the modification is marked as
having been made at the given date or global date and time. If the given value is a global date and time then user agents should use the associated
time-zone offset information to determine which time zone to present the given datetime in.
This value may be shown to the user, but it is primarily intended for
private use.
The cite IDL attribute must reflect
the element's cite content attribute. The dateTime IDL attribute must reflect the
element's datetime content attribute.
4.7.4 Edits and paragraphs
This section is non-normative.
Since the ins and del elements do not affect paragraphing, it is possible, in some cases where paragraphs are implied (without explicit p elements), for an
ins or del element to span both an entire paragraph or other
non-phrasing content elements and part of another paragraph. For example:
<section>
<ins>
<p>
This is a paragraph that was inserted.
</p>
This is another paragraph whose first sentence was inserted
at the same time as the paragraph above.
</ins>
This is a second sentence, which was there all along.
</section>
By only wrapping some paragraphs in p elements, one can even get the end of one
paragraph, a whole second paragraph, and the start of a third paragraph to be covered by the same
ins or del element (though this is very confusing, and not considered
good practice):
<section>
This is the first paragraph. <ins>This sentence was
inserted.
<p>This second paragraph was inserted.</p>
This sentence was inserted too.</ins> This is the
third paragraph in this example.
<!-- (don't do this) -->
</section>
However, due to the way implied paragraphs are defined, it is
not possible to mark up the end of one paragraph and the start of the very next one using the same
ins or del element. You instead have to use one (or two) p
element(s) and two ins or del elements, as for example:
<section>
<p>This is the first paragraph. <del>This sentence was
deleted.</del></p>
<p><del>This sentence was deleted too.</del> That
sentence needed a separate <del> element.</p>
</section>
Partly because of the confusion described above, authors are strongly encouraged to always mark
up all paragraphs with the p element, instead of having ins or
del elements that cross implied paragraphs
boundaries.
4.7.5 Edits and lists
This section is non-normative.
The content models of the ol and ul elements do not allow
ins and del elements as children. Lists always represent all their
items, including items that would otherwise have been marked as deleted.
To indicate that an item is inserted or deleted, an ins or del
element can be wrapped around the contents of the li element. To indicate that an
item has been replaced by another, a single li element can have one or more
del elements followed by one or more ins elements.
In the following example, a list that started empty had items added and removed from it over
time. The bits in the example that have been emphasized show the parts that are the "current"
state of the list. The list item numbers don't take into account the edits, though.
<h1>Stop-ship bugs</h1>
<ol>
<li><ins datetime="2008-02-12T15:20Z">Bug 225:
Rain detector doesn't work in snow</ins></li>
<li><del datetime="2008-03-01T20:22Z"><ins datetime="2008-02-14T12:02Z">Bug 228:
Water buffer overflows in April</ins></del></li>
<li><ins datetime="2008-02-16T13:50Z">Bug 230:
Water heater doesn't use renewable fuels</ins></li>
<li><del datetime="2008-02-20T21:15Z"><ins datetime="2008-02-16T14:25Z">Bug 232:
Carbon dioxide emissions detected after startup</ins></del></li>
</ol>
In the following example, a list that started with just fruit was replaced by a list with just
colors.
The elements that form part of the table model have complicated content model requirements that
do not allow for the ins and del elements, so indicating edits to a
table can be difficult.
To indicate that an entire row or an entire column has been added or removed, the entire
contents of each cell in that row or column can be wrapped in ins or del
elements (respectively).
Generally speaking, there is no good way to indicate more complicated edits (e.g. that a cell
was removed, moving all subsequent cells up or to the left).
